bireader 3.1.9 → 3.1.10

package/README.md

@@ -17,6 +17,7 @@ Supported data types:
 ## What's New?
 
 ### v3
+ * Added ``enforceBigInt`` option for always returning a ``BigInt`` type on 64 bit reads, otherwise will return a ``number`` if integer safe.
  * Added Browser, Node CommonJS and Node ESM modules.
  * Added new ``BiReaderStream`` and ``BiWriterStream`` (Node only) that works without loading the whole file into memory. See [documention](#bistreams) for how to use.
  * Added ``.deleteFile()`` and ``.renameFile(filePath)``.
@@ -311,14 +312,14 @@ Common functions for setup, movement, manipulation and math shared by both.
   <tr>
   <tr>
     <td>Name</td>
-    <td>new BiReader(<b>data</b>, {byteOffset, bitOffset, endianess, strict, extendBufferSize})</td>
-    <td align="center" rowspan="2"><b>Buffer or Uint8Array</b>, byte offset (default 0), bit offset (default 0), endian big or little (default little), strict mode true to restrict extending initially supplied data (default true for reader, false for writer), extended Buffer size amount.
+    <td>new BiReader(<b>data</b>, {byteOffset, bitOffset, endianess, strict, extendBufferSize, enforceBigInt})</td>
+    <td align="center" rowspan="2"><b>Buffer or Uint8Array</b>, byte offset (default 0), bit offset (default 0), endian big or little (default little), strict mode true to restrict extending initially supplied data (default true for reader, false for writer), extended Buffer size amount, always return BigInt values on 64 bit reads.
     </td>
-    <td rowspan="2">Start with new Constructor.<br><br><b>Note:</b> Supplied data can always be found with <b>.data</b>.<br><br><b>Writing data note:</b> while BiWriter can be created with a 0 length Uint8Array or Buffer, each new value write will create a new array and concat the two. For large data writes this will lead to a degraded performance. It's best to supply a larger than needed buffer when creating the Writer and use <b>.trim()</b> after you're finished. You can also set the <b>extendBufferSize</b> value to always extend by a fixed amount when reaching the end. This will also change the logic for <b>.return</b> and <b>.get</b> to trim the remining data from the current position for you. Use <b>.data</b> instead if you want to get the whole padded buffer array.</td>
+    <td rowspan="2">Start with new Constructor.<br><br><b>Note:</b> Supplied data can always be found with <b>.data</b>.<br><br><b>Writing data note:</b> while BiWriter can be created with a 0 length Uint8Array or Buffer, each new value write will create a new array and concat the two. For large data writes this will lead to a degraded performance. It's best to supply a larger than needed buffer when creating the Writer and use <b>.trim()</b> after you're finished. <br><br> You can set the <b>extendBufferSize</b> value to always extend by a fixed amount when reaching the end. This will also change the logic for <b>.return</b> and <b>.get</b> to trim the remining data from the current position for you. Use <b>.data</b> instead if you want to get the whole padded buffer array.</td>
   </tr>
   <tr>
     <td>Name</td>
-    <td>new BiWriter(data, {byteOffset, bitOffset, endianess, strict, extendBufferSize})</td>
+    <td>new BiWriter(data, {byteOffset, bitOffset, endianess, strict, extendBufferSize, enforceBigInt})</td>
   </tr>
   <tr>
     <td>Name</td>

package/dist/index.browser.d.ts

@@ -22,6 +22,12 @@ type BiOptions = {
      * Amount of data to add when extending the buffer array when strict mode is false. Note: Changes login in ``.get`` and ``.return``.
      */
     extendBufferSize?: number;
+    /**
+     * When reading a 64 bit value, the reader checks if the value is safe for a ``number`` type and convert it.
+     *
+     * Set this to ``true`` if you wish for it to always stay a ``BigInt``.
+     */
+    enforceBigInt?: boolean;
 };
 type hexdumpOptions = {
     /**
@@ -140,6 +146,7 @@ declare class BiBase {
      */
     private strDefaults;
     maxFileSize: number | null;
+    enforceBigInt: boolean;
     constructor();
     /**
      * Settings for when using .str
@@ -1282,11 +1289,13 @@ declare class BiBase {
     /**
      * Read signed 64 bit integer.
      *
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
      * @param {boolean} unsigned - if value is unsigned or not
      * @param {endian?} endian - ``big`` or ``little``
-     * @returns {bigint}
+     * @returns {BigValue}
      */
-    readInt64(unsigned?: boolean, endian?: endian): bigint;
+    readInt64(unsigned?: boolean, endian?: endian): BigValue;
     /**
      * Write 64 bit integer.
      *
@@ -1329,33 +1338,43 @@ declare class BiBase {
     /**
      * Read unsigned 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    readUInt64(): bigint;
+    readUInt64(): BigValue;
     /**
      * Read signed 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    readInt64BE(): bigint;
+    readInt64BE(): BigValue;
     /**
      * Read unsigned 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    readUInt64BE(): bigint;
+    readUInt64BE(): BigValue;
     /**
      * Read signed 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    readInt64LE(): bigint;
+    readInt64LE(): BigValue;
     /**
      * Read unsigned 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    readUInt64LE(): bigint;
+    readUInt64LE(): BigValue;
     /**
      * Read double float.
      *
@@ -1427,11 +1446,12 @@ declare class BiBase {
  *
  * @param {Buffer|Uint8Array} data - ``Buffer`` or ``Uint8Array``. Always found in ``BiReader.data``
  * @param {BiOptions?} options - Any options to set at start
- * @param {number?} options.byteOffset - Byte offset to start reader (default ``0``)
- * @param {number?} options.bitOffset - Bit offset 0-7 to start reader (default ``0``)
- * @param {string?} options.endianness - Endianness ``big`` or ``little`` (default ``little``)
- * @param {boolean?} options.strict - Strict mode: if ``true`` does not extend supplied array on outside write (default ``true``)
- * @param {number?} options.extendBufferSize - Amount of data to add when extending the buffer array when strict mode is false. Note: Changes logic in ``.get`` and ``.return``.
+ * @param {BiOptions["byteOffset"]?} options.byteOffset - Byte offset to start writer (default ``0``)
+ * @param {BiOptions["bitOffset"]?} options.bitOffset - Bit offset 0-7 to start writer (default ``0``)
+ * @param {BiOptions["endianness"]?} options.endianness - Endianness ``big`` or ``little`` (default ``little``)
+ * @param {BiOptions["strict"]?} options.strict - Strict mode: if ``true`` does not extend supplied array on outside write (default ``false``)
+ * @param {BiOptions["extendBufferSize"]?} options.extendBufferSize - Amount of data to add when extending the buffer array when strict mode is false. Note: Changes logic in ``.get`` and ``.return``.
+ * @param {BiOptions["enforceBigInt"]?} options.enforceBigInt - 64 bit value reads will always stay ``BigInt``.
  *
  * @since 2.0
  */
@@ -1441,11 +1461,12 @@ declare class BiReader extends BiBase {
      *
      * @param {Buffer|Uint8Array} data - ``Buffer`` or ``Uint8Array``. Always found in ``BiReader.data``
      * @param {BiOptions?} options - Any options to set at start
-     * @param {number?} options.byteOffset - Byte offset to start reader (default ``0``)
-     * @param {number?} options.bitOffset - Bit offset 0-7 to start reader (default ``0``)
-     * @param {string?} options.endianness - Endianness ``big`` or ``little`` (default ``little``)
-     * @param {boolean?} options.strict - Strict mode: if ``true`` does not extend supplied array on outside write (default ``true``)
-     * @param {number?} options.extendBufferSize - Amount of data to add when extending the buffer array when strict mode is false. Note: Changes logic in ``.get`` and ``.return``.
+     * @param {BiOptions["byteOffset"]?} options.byteOffset - Byte offset to start writer (default ``0``)
+     * @param {BiOptions["bitOffset"]?} options.bitOffset - Bit offset 0-7 to start writer (default ``0``)
+     * @param {BiOptions["endianness"]?} options.endianness - Endianness ``big`` or ``little`` (default ``little``)
+     * @param {BiOptions["strict"]?} options.strict - Strict mode: if ``true`` does not extend supplied array on outside write (default ``false``)
+     * @param {BiOptions["extendBufferSize"]?} options.extendBufferSize - Amount of data to add when extending the buffer array when strict mode is false. Note: Changes logic in ``.get`` and ``.return``.
+     * @param {BiOptions["enforceBigInt"]?} options.enforceBigInt - 64 bit value reads will always stay ``BigInt``.
      */
     constructor(data: Buffer | Uint8Array, options?: BiOptions);
     /**
@@ -3376,111 +3397,147 @@ declare class BiReader extends BiBase {
     /**
      * Read signed 64 bit integer
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get int64(): bigint;
+    get int64(): BigValue;
     /**
      * Read signed 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get bigint(): bigint;
+    get bigint(): BigValue;
     /**
      * Read signed 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get quad(): bigint;
+    get quad(): BigValue;
     /**
      * Read unsigned 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get uint64(): bigint;
+    get uint64(): BigValue;
     /**
      * Read unsigned 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get ubigint(): bigint;
+    get ubigint(): BigValue;
     /**
      * Read unsigned 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get uquad(): bigint;
+    get uquad(): BigValue;
     /**
      * Read signed 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get int64be(): bigint;
+    get int64be(): BigValue;
     /**
      * Read signed 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get bigintbe(): bigint;
+    get bigintbe(): BigValue;
     /**
      * Read signed 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get quadbe(): bigint;
+    get quadbe(): BigValue;
     /**
      * Read unsigned 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get uint64be(): bigint;
+    get uint64be(): BigValue;
     /**
      * Read unsigned 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get ubigintbe(): bigint;
+    get ubigintbe(): BigValue;
     /**
      * Read unsigned 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get uquadbe(): bigint;
+    get uquadbe(): BigValue;
     /**
      * Read signed 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get int64le(): bigint;
+    get int64le(): BigValue;
     /**
      * Read signed 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get bigintle(): bigint;
+    get bigintle(): BigValue;
     /**
      * Read signed 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get quadle(): bigint;
+    get quadle(): BigValue;
     /**
      * Read unsigned 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get uint64le(): bigint;
+    get uint64le(): BigValue;
     /**
      * Read unsigned 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get ubigintle(): bigint;
+    get ubigintle(): BigValue;
     /**
      * Read unsigned 64 bit integer.
      *
-     * @returns {bigint}
+     * Note: If ``enforceBigInt`` was set to ``true``, this always returns a ``BigInt`` otherwise it will return a ``number`` if integer safe.
+     *
+     * @returns {BigValue}
      */
-    get uquadle(): bigint;
+    get uquadle(): BigValue;
     /**
      * Read double float.
      *
@@ -3797,6 +3854,7 @@ declare class BiReader extends BiBase {
  * @param {BiOptions["endianness"]?} options.endianness - Endianness ``big`` or ``little`` (default ``little``)
  * @param {BiOptions["strict"]?} options.strict - Strict mode: if ``true`` does not extend supplied array on outside write (default ``false``)
  * @param {BiOptions["extendBufferSize"]?} options.extendBufferSize - Amount of data to add when extending the buffer array when strict mode is false. Note: Changes logic in ``.get`` and ``.return``.
+ * @param {BiOptions["enforceBigInt"]?} options.enforceBigInt - 64 bit value reads will always stay ``BigInt``.
  *
  * @since 2.0
  */
@@ -3811,6 +3869,7 @@ declare class BiWriter extends BiBase {
      * @param {BiOptions["endianness"]?} options.endianness - Endianness ``big`` or ``little`` (default ``little``)
      * @param {BiOptions["strict"]?} options.strict - Strict mode: if ``true`` does not extend supplied array on outside write (default ``false``)
      * @param {BiOptions["extendBufferSize"]?} options.extendBufferSize - Amount of data to add when extending the buffer array when strict mode is false. Note: Changes logic in ``.get`` and ``.return``.
+     * @param {BiOptions["enforceBigInt"]?} options.enforceBigInt - 64 bit value reads will always stay ``BigInt``.
      */
     constructor(data?: Buffer | Uint8Array, options?: BiOptions);
     /**