bireader 1.0.13 → 1.0.15

package/lib/esm/src/reader.js

@@ -1,39 +1,50 @@
+import { skip, goto, remove, checkSize, addData, hexDump } from './common';
 /**
+* Binary reader, includes bitfields and strings
 *
-* byte reader, includes bitfields and strings
-*
-* @param {Buffer|Uint8Array} data - ```Buffer``` or ```Uint8Array```
-* @param {number} byteOffset - byte offset to start reader, default is 0
-* @param {number} bitOffset - bit offset to start reader, 0-7
-* @param {string} endianness - endianness ```big``` or ```little``` (default ```little```)
+* @param {Buffer|Uint8Array} data - ```Buffer``` or ```Uint8Array```. Always found in ``biwriter.data``
+* @param {number} byteOffset - Byte offset to start reader (default 0)
+* @param {number} bitOffset - Bit offset 0-7 to start reader (default 0)
+* @param {string} endianness - Endianness ```big``` or ```little``` (default ```little```)
+* @param {boolean} strict - Strict mode: if true does not extend supplied array on outside write (default true)
 */
 export class bireader {
-    check_size(read_size, read_bits) {
-        const new_off = this.offset + (read_size || 0) + Math.ceil((this.bitoffset + (read_bits || 0)) / 8);
-        if (new_off > this.size) {
-            throw new Error(`Reader reached end of data.`);
-        }
-    }
     isBuffer(obj) {
         return (typeof Buffer !== 'undefined' && obj instanceof Buffer);
     }
     isBufferOrUint8Array(obj) {
         return obj instanceof Uint8Array || this.isBuffer(obj);
     }
+    extendArray(to_padd) {
+        if ((typeof Buffer !== 'undefined' && this.data instanceof Buffer)) {
+            var paddbuffer = Buffer.alloc(to_padd);
+            this.data = Buffer.concat([this.data, paddbuffer]);
+        }
+        else {
+            const addArray = new Array(to_padd);
+            this.data = new Uint8Array([...this.data, ...addArray]);
+        }
+    }
+    check_size(read_size, read_bits) {
+        return checkSize(this, read_size || 0, read_bits || 0, this.offset);
+    }
     /**
+    * Binary reader, includes bitfields and strings
     *
-    * byte reader, includes bitfields and strings
-    *
-    * @param {Buffer|Uint8Array} data - ```Buffer``` or ```Uint8Array```
-    * @param {number} byteOffset - byte offset to start reader, default is 0
-    * @param {number} bitOffset - bit offset to start reader, 0-7
-    * @param {string} endianness - endianness ```big``` or ```little``` (default ```little```)
+    * @param {Buffer|Uint8Array} data - ```Buffer``` or ```Uint8Array```. Always found in ``biwriter.data``
+    * @param {number} byteOffset - Byte offset to start reader (default 0)
+    * @param {number} bitOffset - Bit offset 0-7 to start reader (default 0)
+    * @param {string} endianness - Endianness ```big``` or ```little``` (default ```little```)
+    * @param {boolean} strict - Strict mode: if true does not extend supplied array on outside write (default true)
     */
-    constructor(data, byteOffset, bitOffset, endianness) {
+    constructor(data, byteOffset, bitOffset, endianness, strict) {
         this.endian = "little";
         this.offset = 0;
         this.bitoffset = 0;
         this.size = 0;
+        this.strict = false;
+        this.errorDump = true;
+        this.data = [];
         if (endianness != undefined && typeof endianness != "string") {
             throw new Error("Endian must be big or little");
         }
@@ -52,6 +63,14 @@ export class bireader {
         if (bitOffset != undefined) {
             this.bitoffset = bitOffset % 8;
         }
+        if (typeof strict == "boolean") {
+            this.strict = strict;
+        }
+        else {
+            if (strict != undefined) {
+                throw new Error("Strict mode must be true of false");
+            }
+        }
         if (data == undefined) {
             throw new Error("Data required");
         }
@@ -116,123 +135,98 @@ export class bireader {
     le() {
         this.endianness("little");
     }
+    //
+    // move from current position
+    //
     /**
-    * Move current read byte or bit position
+    * Offset current byte or bit position
+    * Note: Will extend array if strict mode is off and outside of max size
     *
-    * @param {number} bytes - bytes to skip
-    * @param {number} bits - bits to skip
+    * @param {number} bytes - Bytes to skip
+    * @param {number} bits - Bits to skip (0-7)
     */
     skip(bytes, bits) {
-        this.check_size(bytes || 0);
-        if ((((bytes || 0) + this.offset) + Math.ceil((this.bitoffset + (bits || 0)) / 8)) > this.size) {
-            throw new Error("Seek outside of size of data: " + this.size);
-        }
-        this.bitoffset += (bits || 0) % 8;
-        this.offset += (bytes || 0);
+        return skip(this, bytes, bits);
     }
     /**
-    * Move current read byte or bit position
+    * Offset current byte or bit position
+    * Note: Will extend array if strict mode is off and outside of max size
     *
-    * @param {number} bytes - bytes to skip
-    * @param {number} bits - bits to skip
+    * @param {number} bytes - Bytes to skip
+    * @param {number} bits - Bits to skip (0-7)
     */
-    fskip(bytes, bits) {
+    jump(bytes, bits) {
         this.skip(bytes, bits);
     }
+    //
+    // directly set current position
+    //
     /**
-    * Change current byte or bit read position
+    * Change position directly to address
+    * Note: Will extend array if strict mode is off and outside of max size
     *
-    * @param {number} byte - byte to jump to
-    * @param {number} bit - bit to jump to (0-7)
+    * @param {number} byte - byte to set to
+    * @param {number} bit - bit to set to (0-7)
     */
     goto(byte, bit) {
-        if ((byte + Math.ceil((bit || 0) / 8)) > this.size) {
-            throw new Error("Goto outside of size of data: " + this.size);
-        }
-        this.offset = byte;
-        this.bitoffset = (bit || 0) % 8;
+        return goto(this, byte, bit);
     }
     /**
-    * Change current byte or bit read position
+    * Change position directly to address
+    * Note: Will extend array if strict mode is off and outside of max size
     *
-    * @param {number} byte - byte to jump to
-    * @param {number} bit - bit to jump to (0-7)
+    * @param {number} byte - byte to set to
+    * @param {number} bit - bit to set to (0-7)
     */
     seek(byte, bit) {
-        this.goto(byte, bit);
-    }
-    /**
-    * Change current byte or bit read position
-    *
-    * @param {number} byte - byte to jump to
-    * @param {number} bit - bit to jump to (0-7)
-    */
-    fseek(byte, bit) {
-        this.goto(byte, bit);
+        return this.goto(byte, bit);
     }
     /**
-    * Change current byte or bit read position
+    * Change position directly to address
+    * Note: Will extend array if strict mode is off and outside of max size
     *
-    * @param {number} byte - byte to jump to
-    * @param {number} bit - bit to jump to (0-7)
-    */
-    jump(byte, bit) {
-        this.goto(byte, bit);
-    }
-    /**
-    * Change current byte or bit read position
-    *
-    * @param {number} byte - byte to jump to
-    * @param {number} bit - bit to jump to (0-7)
+    * @param {number} byte - byte to set to
+    * @param {number} bit - bit to set to (0-7)
     */
     pointer(byte, bit) {
-        this.goto(byte, bit);
+        return this.goto(byte, bit);
     }
     /**
-    * Change current byte or bit read position
+    * Change position directly to address
+    * Note: Will extend array if strict mode is off and outside of max size
     *
-    * @param {number} byte - byte to jump to
-    * @param {number} bit - bit to jump to (0-7)
+    * @param {number} byte - byte to set to
+    * @param {number} bit - bit to set to (0-7)
     */
     warp(byte, bit) {
-        this.goto(byte, bit);
-    }
-    /**
-    * Change current byte or bit read position
-    *
-    * @param {number} byte - byte to jump to
-    * @param {number} bit - bit to jump to (0-7)
-    */
-    fsetpos(byte, bit) {
-        this.goto(byte, bit);
+        return this.goto(byte, bit);
     }
+    //
+    //go to start
+    //
     /**
-    * Set offset to start of file
+    * Set byte and bit position to start of data
     */
     rewind() {
         this.offset = 0;
         this.bitoffset = 0;
     }
     /**
-    * Set offset to start of file
+    * Set byte and bit position to start of data
     */
     gotostart() {
         this.offset = 0;
         this.bitoffset = 0;
     }
-    /**
-    * Set offset to start of file
-    */
-    tostart() {
-        this.offset = 0;
-        this.bitoffset = 0;
-    }
+    //
+    //get position
+    //
     /**
     * Get the current byte position
     *
     * @return {number} current byte position
     */
-    ftell() {
+    tell() {
         return this.offset;
     }
     /**
@@ -240,7 +234,7 @@ export class bireader {
     *
     * @return {number} current byte position
     */
-    tell() {
+    getOffset() {
         return this.offset;
     }
     /**
@@ -248,95 +242,204 @@ export class bireader {
     *
     * @return {number} current byte position
     */
-    fgetpos() {
+    saveOffset() {
         return this.offset;
     }
+    //
+    //strict mode change
+    //
     /**
-    * Get the current byte position
+    * Disallows extending data if position is outside of max size
+    */
+    restrict() {
+        this.strict = true;
+    }
+    /**
+    * Allows extending data if position is outside of max size
+    */
+    unrestrict() {
+        this.strict = false;
+    }
+    //
+    //remove part of data
+    //
+    /**
+    * Deletes part of data from start to current byte position unless supplied, returns removed
+    * Note: Errors in strict mode
     *
-    * @return {number} current byte position
+    * @param {number} startOffset - Start location (default 0)
+    * @param {number} endOffset - End location (default current position)
+    * @param {boolean} consume - Move position to end of removed data (default false)
+    * @returns {Buffer|Uint8Array} Removed data as ``Buffer`` or ``Uint8Array``
     */
-    saveOffset() {
-        return this.offset;
+    delete(startOffset, endOffset, consume) {
+        return remove(this, startOffset || 0, endOffset || this.offset, consume || false, true);
     }
     /**
-    * Truncates array from start to current position unless supplied
-    * Note: Does not affect supplied data
-    * @param {number} startOffset - Start location, default 0
-    * @param {number} endOffset - end location, default current write position
-    * @returns {Buffer|Uint8Array} ``Buffer`` or ``Uint8Array``
+    * Deletes part of data from start to current byte position unless supplied, returns removed
+    * Note: Errors in strict mode
+    *
+    * @param {number} startOffset - Start location (default 0)
+    * @param {number} endOffset - End location (default current position)
+    * @param {boolean} consume - Move position to end of removed data (default false)
+    * @returns {Buffer|Uint8Array} Removed data as ``Buffer`` or ``Uint8Array``
     */
-    clip(startOffset, endOffset) {
-        return this.data.slice(startOffset || 0, endOffset || this.offset);
+    clip(startOffset, endOffset, consume) {
+        return remove(this, startOffset || 0, endOffset || this.offset, consume || false, true);
     }
     /**
-    * Truncates array from start to current position unless supplied
-    * Note: Does not affect supplied data
-    * @param {number} startOffset - Start location, default 0
-    * @param {number} endOffset - end location, default current write position
-    * @returns {Buffer|Uint8Array} ``Buffer`` or ``Uint8Array``
+    * Deletes part of data from current byte position to supplied length, returns removed
+    * Note: Errors in strict mode
+    *
+    * @param {number} length - Length of data in bytes to remove
+    * @param {boolean} consume - Move position to end of removed data (default false)
+    * @returns {Buffer|Uint8Array} Removed data as ``Buffer`` or ``Uint8Array``
     */
-    crop(startOffset, endOffset) {
-        return this.data.slice(startOffset || 0, endOffset || this.offset);
+    crop(length, consume) {
+        return remove(this, this.offset, this.offset + (length || 0), consume || false, true);
     }
     /**
-    * Truncates array from start to current position unless supplied
-    * Note: Does not affect supplied data
-    * @param {number} startOffset - Start location, default 0
-    * @param {number} endOffset - end location, default current write position
-    * @returns {Buffer|Uint8Array} ``Buffer`` or ``Uint8Array``
+    * Deletes part of data from current position to supplied length, returns removed
+    * Note: Only works in strict mode
+    *
+    * @param {number} length - Length of data in bytes to remove
+    * @param {boolean} consume - Move position to end of removed data (default false)
+    * @returns {Buffer|Uint8Array} Removed data as ``Buffer`` or ``Uint8Array``
+    */
+    drop(length, consume) {
+        return remove(this, this.offset, this.offset + (length || 0), consume || false, true);
+    }
+    //
+    //copy out
+    //
+    /**
+    * Returns part of data from current byte position to end of data unless supplied
+    *
+    * @param {number} startOffset - Start location (default current position)
+    * @param {number} endOffset - End location (default end of data)
+    * @param {boolean} consume - Move position to end of lifted data (default false)
+    * @param {number} fillValue - Byte value to to fill returned data (does NOT fill unless supplied)
+    * @returns {Buffer|Uint8Array} Selected data as ```Uint8Array``` or ```Buffer```
     */
-    truncate(startOffset, endOffset) {
-        return this.data.slice(startOffset || 0, endOffset || this.offset);
+    lift(startOffset, endOffset, consume, fillValue) {
+        return remove(this, startOffset || this.offset, endOffset || this.size, consume || false, false, fillValue);
     }
     /**
-    * Truncates array from start to current position unless supplied
-    * Note: Does not affect supplied data
-    * @param {number} startOffset - Start location, default 0
-    * @param {number} endOffset - end location, default current write position
-    * @returns {Buffer|Uint8Array} ``Buffer`` or ``Uint8Array``
+    * Returns part of data from current byte position to end of data unless supplied
+    *
+    * @param {number} startOffset - Start location (default current position)
+    * @param {number} endOffset - End location (default end of data)
+    * @param {boolean} consume - Move position to end of lifted data (default false)
+    * @param {number} fillValue - Byte value to to fill returned data (does NOT fill unless supplied)
+    * @returns {Buffer|Uint8Array} Selected data as ```Uint8Array``` or ```Buffer```
     */
-    slice(startOffset, endOffset) {
-        return this.data.slice(startOffset || 0, endOffset || this.offset);
+    fill(startOffset, endOffset, consume, fillValue) {
+        return remove(this, startOffset || this.offset, endOffset || this.size, consume || false, false, fillValue);
     }
     /**
-    * Extract array from current position to length supplied
+    * Extract data from current position to length supplied
     * Note: Does not affect supplied data
-    * @param {number} length - length of data to copy from current offset
-    * @returns {Buffer|Uint8Array} ``Buffer`` or ``Uint8Array``
+    *
+    * @param {number} length - Length of data in bytes to copy from current offset
+    * @param {number} consume - Moves offset to end of length
+    * @returns {Buffer|Uint8Array} Selected data as ```Uint8Array``` or ```Buffer```
     */
-    extract(length) {
-        if (this.offset + (length || 0) > this.size) {
-            throw new Error("End offset outside of data: " + this.size);
-        }
-        return this.data.slice(this.offset, this.offset + (length || 0));
+    extract(length, consume) {
+        return remove(this, this.offset, length || 0, consume || false, false);
     }
     /**
-    * Extract array from current position to length supplied
+    * Extract data from current position to length supplied
     * Note: Does not affect supplied data
-    * @param {number} length - length of data to copy from current offset
-    * @returns {Buffer|Uint8Array} ``Buffer`` or ``Uint8Array``
+    *
+    * @param {number} length - Length of data in bytes to copy from current offset
+    * @param {number} consume - Moves offset to end of length
+    * @returns {Buffer|Uint8Array} Selected data as ```Uint8Array``` or ```Buffer```
     */
-    wrap(length) {
-        if (this.offset + (length || 0) > this.size) {
-            throw new Error("End offset outside of data: " + this.size);
-        }
-        return this.data.slice(this.offset, this.offset + (length || 0));
+    slice(length, consume) {
+        return remove(this, this.offset, length || 0, consume || false, false);
     }
     /**
-    * Extract array from current position to length supplied
+    * Extract data from current position to length supplied
     * Note: Does not affect supplied data
-    * @param {number} length - length of data to copy from current offset
-    * @returns {Buffer|Uint8Array} ``Buffer`` or ``Uint8Array``
+    *
+    * @param {number} length - Length of data in bytes to copy from current offset
+    * @param {number} consume - Moves offset to end of length
+    * @returns {Buffer|Uint8Array} Selected data as ```Uint8Array``` or ```Buffer```
     */
-    lift(length) {
-        if (this.offset + (length || 0) > this.size) {
-            throw new Error("End offset outside of data: " + this.size);
-        }
-        return this.data.slice(this.offset, this.offset + (length || 0));
+    wrap(length, consume) {
+        return remove(this, this.offset, length || 0, consume || false, false);
+    }
+    //
+    //insert
+    //
+    /**
+    * Inserts data into data
+    * Note: Must be same data type as supplied data. Errors on strict mode.
+    *
+    * @param {Buffer|Uint8Array} data - ```Uint8Array``` or ```Buffer``` to add to data
+    * @param {boolean} consume - Move current write position to end of data (default false)
+    * @param {number} offset - Offset to add it at (defaults to current position)
+    */
+    insert(data, consume, offset) {
+        return addData(this, data, consume || false, offset || this.offset);
+    }
+    /**
+    * Inserts data into data
+    * Note: Must be same data type as supplied data. Errors on strict mode.
+    *
+    * @param {Buffer|Uint8Array} data - ```Uint8Array``` or ```Buffer``` to add to data
+    * @param {boolean} consume - Move current write position to end of data (default false)
+    * @param {number} offset - Offset to add it at (defaults to current position)
+    */
+    place(data, consume, offset) {
+        return addData(this, data, consume || false, offset || this.offset);
+    }
+    /**
+    * Adds data to start of supplied data
+    * Note: Must be same data type as supplied data. Errors on strict mode.
+    *
+    * @param {Buffer|Uint8Array} data - ```Uint8Array``` or ```Buffer``` to add to data
+    * @param {boolean} consume - Move current write position to end of data (default false)
+    */
+    unshift(data, consume) {
+        return addData(this, data, consume || false, 0);
     }
     /**
+    * Adds data to start of supplied data
+    * Note: Must be same data type as supplied data. Errors on strict mode.
+    *
+    * @param {Buffer|Uint8Array} data - ```Uint8Array``` or ```Buffer``` to add to data
+    * @param {boolean} consume - Move current write position to end of data (default false)
+    */
+    prepend(data, consume) {
+        return addData(this, data, consume || false, 0);
+    }
+    /**
+    * Adds data to end of supplied data
+    * Note: Must be same data type as supplied data. Errors on strict mode.
+    *
+    * @param {Buffer|Uint8Array} data - ```Uint8Array``` or ```Buffer``` to add to data
+    * @param {boolean} consume - Move current write position to end of data (default false)
+    */
+    push(data, consume) {
+        return addData(this, data, consume || false, this.size);
+    }
+    /**
+    * Adds data to end of supplied data
+    * Note: Must be same data type as supplied data. Errors on strict mode.
+    *
+    * @param {Buffer|Uint8Array} data - ```Uint8Array``` or ```Buffer``` to add to data
+    * @param {boolean} consume - Move current write position to end of data (default false)
+    */
+    append(data, consume) {
+        return addData(this, data, consume || false, this.size);
+    }
+    //
+    //finishing
+    //
+    /**
     * Returns current data
+    *
     * @returns {Buffer|Uint8Array} ``Buffer`` or ``Uint8Array``
     */
     get() {
@@ -344,34 +447,62 @@ export class bireader {
     }
     /**
     * Returns current data
+    *
     * @returns {Buffer|Uint8Array} ``Buffer`` or ``Uint8Array``
     */
     return() {
         return this.data;
     }
     /**
-    * removes reading data
+    * removes data
     */
     end() {
-        this.data = [];
+        this.data = undefined;
     }
     /**
-    * removes reading data
+    * removes data
     */
     close() {
-        this.data = [];
+        this.data = undefined;
     }
     /**
-    * removes reading data
+    * removes data
     */
     done() {
-        this.data = [];
+        this.data = undefined;
     }
     /**
-    * removes reading data
+    * removes data
     */
     finished() {
-        this.data = [];
+        this.data = undefined;
+    }
+    /**
+    * Console logs data as hex dump
+    *
+    * @param {object} options - options object
+    * ```javascript
+    *   {
+    *       length: 192, // number of bytes to log, default 192 or end of data
+    *       startByte: 0, // byte to start dump, default current position
+    *       supressUnicode: false // Supress unicode character preview for cleaner columns
+    *   }
+    * ```
+    */
+    hexdump(options) {
+        return hexDump(this, options);
+    }
+    /**
+    * Turn hexdump on error off (default on)
+    */
+    errorDumpOff() {
+        this.errorDump = false;
+    }
+    /**
+    * Turn hexdump on error on (default on)
+    */
+    errorDumpOn() {
+        this.errorDump = true;
     }
     //
     //bit reader
@@ -395,6 +526,7 @@ export class bireader {
         }
         const size_needed = ((((bits - 1) + this.bitoffset) / 8) + this.offset);
         if (bits <= 0 || size_needed > this.size) {
+            this.errorDump ? "[Error], hexdump:\n" + this.hexdump() : "";
             throw new Error("Invalid number of bits to read: " + size_needed + " of " + this.size);
         }
         var off_in_bits = (this.offset * 8) + this.bitoffset;
@@ -421,7 +553,7 @@ export class bireader {
         }
         this.offset = this.offset + Math.floor(((bits) + this.bitoffset) / 8); //end byte
         this.bitoffset = ((bits) + this.bitoffset) % 8;
-        if (unsigned == true) {
+        if (unsigned == true || bits <= 7) {
             return value >>> 0;
         }
         if (bits !== 32 && value & (1 << (bits - 1))) {
@@ -443,13 +575,13 @@ export class bireader {
         return this.readBit(bits, unsigned, endian);
     }
     /**
-* Bit field reader
-*
-* Note: When returning to a byte read, remaining bits are dropped
-*
-* @param {boolean} unsigned - if the value is unsigned
-* @returns number
-*/
+    * Bit field reader
+    *
+    * Note: When returning to a byte read, remaining bits are dropped
+    *
+    * @param {boolean} unsigned - if the value is unsigned
+    * @returns number
+    */
     bit1(unsigned) {
         return this.bit(1, unsigned);
     }
@@ -3729,6 +3861,7 @@ export class bireader {
                 maxBytes = this.readInt32(true, endian);
             }
             else {
+                this.errorDump ? "[Error], hexdump:\n" + this.hexdump() : "";
                 throw new Error("Invalid length read size: " + lengthReadSize);
             }
             // Read the string as Pascal or Delphi encoded
@@ -3760,6 +3893,23 @@ export class bireader {
             throw new Error('Unsupported string type: ' + stringType);
         }
     }
+    /**
+    * Reads string, use options object for different types
+    *
+    * @param {object} options
+    * ```javascript
+    * {
+    *  length: number, //for fixed length, non-terminate value utf strings
+    *  stringType: "utf-8", //utf-8, utf-16, pascal or wide-pascal
+    *  terminateValue: 0x00, // only for non-fixed length utf strings
+    *  lengthReadSize: 1, //for pascal strings. 1, 2 or 4 byte length read size
+    *  stripNull: true, // removes 0x00 characters
+    *  encoding: "utf-8", //TextEncoder accepted types
+    *  endian: "little", //for wide-pascal and utf-16
+    * }
+    * ```
+    * @return string
+    */
     string(options) {
         return this.readString(options);
     }