@nuintun/buffer 0.3.2 → 0.5.0

package/README.md

@@ -18,11 +18,43 @@
 /**
  * @module Buffer
  */
+
+export type TypedArray =
+  | Int8Array
+  | Int16Array
+  | Int32Array
+  | Uint8Array
+  | Uint16Array
+  | Uint32Array
+  | Float32Array
+  | Float64Array
+  | BigInt64Array
+  | BigUint64Array
+  | Uint8ClampedArray;
+
 export declare enum Endian {
   Big = 0,
   Little = 1
 }
 
+export interface Options {
+  /**
+   * @property {number} [pageSize]
+   * @description 缓存页大小
+   */
+  pageSize?: number;
+  /**
+   * @property {TextEncode} [encode]
+   * @description 文本编码函数
+   */
+  encode?: TextEncode;
+  /**
+   * @property {TextDecode} [decode]
+   * @description 文本解码函数
+   */
+  decode?: TextDecode;
+}
+
 /**
  * @function endianness
  * @description 获取系统默认字节序
@@ -37,17 +69,22 @@ export declare function endianness(): Endian;
 export declare class Buffer {
   /**
    * @constructor
-   * @param {number} [length] 缓冲区初始大小
+   * @param {number} [length] 缓冲区初始字节大小
    * @param {number} [pageSize] 缓冲区分页大小，扩容时将按分页大小增加
    */
-  constructor(length?: number, pageSize?: number);
+  constructor(length?: number, options?: Options);
   /**
    * @constructor
-   * @param {Uint8Array} bytes 缓冲区初始数据
+   * @param {Uint8Array} bytes 缓冲区初始字节数据
    * @param {number} [pageSize] 缓冲区分页大小，扩容时将按分页大小增加
    */
-  constructor(bytes?: Uint8Array, pageSize?: number);
-
+  constructor(bytes: TypedArray, options?: Options);
+  /**
+   * @constructor
+   * @param {ArrayBuffer} buffer 缓冲区初始缓冲数据
+   * @param {number} [pageSize] 缓冲区分页大小，扩容时将按分页大小增加
+   */
+  constructor(buffer: ArrayBuffer, options?: Options);
   /**
    * @public
    * @property {number} offset
@@ -55,7 +92,6 @@ export declare class Buffer {
    * @description 下一次调用读写方法时将在此位置开始读写
    */
   set offset(offset: number);
-
   /**
    * @public
    * @property {number} offset
@@ -63,7 +99,6 @@ export declare class Buffer {
    * @returns {number}
    */
   get offset(): number;
-
   /**
    * @public
    * @property {number} length
@@ -72,7 +107,6 @@ export declare class Buffer {
    * @description 如果将长度设置为大于当前长度的值，则用零填充字节数组的右侧
    */
   set length(length: number);
-
   /**
    * @public
    * @property {number} length
@@ -80,23 +114,20 @@ export declare class Buffer {
    * @returns {number}
    */
   get length(): number;
-
   /**
    * @public
    * @property {ArrayBuffer} buffer
-   * @description 获取 ArrayBuffer 缓冲区
+   * @description 获取全部 ArrayBuffer 原始缓冲区
    * @returns {ArrayBuffer}
    */
   get buffer(): ArrayBuffer;
-
   /**
    * @public
    * @property {Uint8Array} bytes
-   * @description 获取 Uint8Array 缓冲区
+   * @description 获取已写入 Uint8Array 原始缓冲区
    * @returns {Uint8Array}
    */
   get bytes(): Uint8Array;
-
   /**
    * @public
    * @method writeInt8
@@ -104,7 +135,6 @@ export declare class Buffer {
    * @param {number} value 介于 -128 和 127 之间的整数
    */
   writeInt8(value: number): void;
-
   /**
    * @public
    * @method writeUint8
@@ -112,14 +142,12 @@ export declare class Buffer {
    * @param {number} value 介于 0 和 255 之间的整数
    */
   writeUint8(value: number): void;
-
   /**
    * @method writeBoolean
    * @description 在缓冲区中写入布尔值，true 写 1，false写 0
    * @param {boolean} value 布尔值
    */
   writeBoolean(value: boolean): void;
-
   /**
    * @method writeInt16
    * @description 在缓冲区中写入一个 16 位有符号整数
@@ -127,7 +155,6 @@ export declare class Buffer {
    * @param {boolean} [littleEndian] 是否为小端字节序
    */
   writeInt16(value: number, littleEndian?: boolean): void;
-
   /**
    * @method writeUint16
    * @description 在缓冲区中写入一个 16 位无符号整数
@@ -135,7 +162,6 @@ export declare class Buffer {
    * @param {boolean} [littleEndian] 是否为小端字节序
    */
   writeUint16(value: number, littleEndian?: boolean): void;
-
   /**
    * @method writeInt32
    * @description 在缓冲区中写入一个有符号的 32 位有符号整数
@@ -143,7 +169,6 @@ export declare class Buffer {
    * @param {boolean} [littleEndian] 是否为小端字节序
    */
   writeInt32(value: number, littleEndian?: boolean): void;
-
   /**
    * @method writeUint32
    * @description 在缓冲区中写入一个无符号的 32 位无符号整数
@@ -151,15 +176,13 @@ export declare class Buffer {
    * @param {boolean} [littleEndian] 是否为小端字节序
    */
   writeUint32(value: number, littleEndian?: boolean): void;
-
   /**
    * @method writeInt64
-   * @description 在缓冲区中写入一个无符号的 64 位有符号整数
+   * @description 在缓冲区中写入一个 64 位有符号整数
    * @param {bigint} value 要写入的 32 位有符号整数
    * @param {boolean} [littleEndian] 是否为小端字节序
    */
   writeInt64(value: bigint, littleEndian?: boolean): void;
-
   /**
    * @method writeUint64
    * @description 在缓冲区中写入一个无符号的 64 位无符号整数
@@ -167,7 +190,6 @@ export declare class Buffer {
    * @param {boolean} [littleEndian] 是否为小端字节序
    */
   writeUint64(value: bigint, littleEndian?: boolean): void;
-
   /**
    * @method writeFloat32
    * @description 在缓冲区中写入一个 IEEE 754 单精度 32 位浮点数
@@ -175,7 +197,6 @@ export declare class Buffer {
    * @param {boolean} [littleEndian] 是否为小端字节序
    */
   writeFloat32(value: number, littleEndian?: boolean): void;
-
   /**
    * @method writeFloat64
    * @description 在缓冲区中写入一个 IEEE 754 双精度 64 位浮点数
@@ -183,7 +204,6 @@ export declare class Buffer {
    * @param {boolean} [littleEndian] 是否为小端字节序
    */
   writeFloat64(value: number, littleEndian?: boolean): void;
-
   /**
    * @method write
    * @description 将字符串用指定编码写入字节流
@@ -199,28 +219,24 @@ export declare class Buffer {
    * @param {number} [end] Uint8Array 对象结束索引
    */
   write(bytes: Uint8Array, start?: number, end?: number): void;
-
   /**
    * @method readInt8
    * @description 从缓冲区中读取有符号的整数
    * @returns {number} 介于 -128 和 127 之间的整数
    */
   readInt8(): number;
-
   /**
    * @method readUint8
    * @description 从缓冲区中读取无符号的整数
    * @returns {number} 介于 0 和 255 之间的无符号整数
    */
   readUint8(): number;
-
   /**
    * @method readBoolean
    * @description 从缓冲区中读取布尔值
    * @returns {boolean} 如果字节非零，则返回 true，否则返回 false
    */
   readBoolean(): boolean;
-
   /**
    * @method readInt16
    * @description 从缓冲区中读取一个 16 位有符号整数
@@ -228,7 +244,6 @@ export declare class Buffer {
    * @returns {number} 介于 -32768 和 32767 之间的 16 位有符号整数
    */
   readInt16(littleEndian?: boolean): number;
-
   /**
    * @method readUint16
    * @description 从缓冲区中读取一个 16 位无符号整数
@@ -236,7 +251,6 @@ export declare class Buffer {
    * @returns {number} 介于 0 和 65535 之间的 16 位无符号整数
    */
   readUint16(littleEndian?: boolean): number;
-
   /**
    * @method readInt32
    * @description 从缓冲区中读取一个 32 位有符号整数
@@ -244,7 +258,6 @@ export declare class Buffer {
    * @returns {number} 介于 -2147483648 和 2147483647 之间的 32 位有符号整数
    */
   readInt32(littleEndian?: boolean): number;
-
   /**
    * @method readUint32
    * @description 从缓冲区中读取一个 32 位无符号整数
@@ -252,7 +265,6 @@ export declare class Buffer {
    * @returns {number} 介于 0 和 4294967295 之间的 32 位无符号整数
    */
   readUint32(littleEndian?: boolean): number;
-
   /**
    * @method readInt64
    * @description 从缓冲区中读取一个 64 位有符号整数
@@ -260,7 +272,6 @@ export declare class Buffer {
    * @returns {bigint} 介于 -9223372036854775808 和 9223372036854775807 之间的 64 位有符号整数
    */
   readInt64(littleEndian?: boolean): bigint;
-
   /**
    * @method readUint64
    * @description 从缓冲区中读取一个 64 位无符号整数
@@ -268,7 +279,6 @@ export declare class Buffer {
    * @returns {bigint} 介于 0 和 18446744073709551615 之间的 64 位无符号整数
    */
   readUint64(littleEndian?: boolean): bigint;
-
   /**
    * @method readFloat32
    * @description 从缓冲区中读取一个 IEEE 754 单精度 32 位浮点数
@@ -276,7 +286,6 @@ export declare class Buffer {
    * @returns {number} 单精度 32 位浮点数
    */
   readFloat32(littleEndian?: boolean): number;
-
   /**
    * @method readFloat64
    * @description 从缓冲区中读取一个 IEEE 754 双精度 64 位浮点数
@@ -284,7 +293,6 @@ export declare class Buffer {
    * @returns {number} 双精度 64 位浮点数
    */
   readFloat64(littleEndian?: boolean): number;
-
   /**
    * @method read
    * @description 从缓冲区中读取指定长度的 Uint8Array 对象
@@ -300,7 +308,6 @@ export declare class Buffer {
    * @returns {string} 指定编码的字符串
    */
   read(length: number, encoding: string): string;
-
   /**
    * @public
    * @method slice
@@ -310,7 +317,6 @@ export declare class Buffer {
    * @returns {Buffer}
    */
   slice(start?: number, end?: number): Buffer;
-
   /**
    * @public
    * @method copyWithin
@@ -321,7 +327,24 @@ export declare class Buffer {
    * @returns {this}
    */
   copyWithin(target: number, start: number, end?: number): this;
-
+  /**
+   * @method entries
+   * @description 获取迭代器
+   * @returns {IterableIterator<[number, number]>}
+   */
+  entries(): IterableIterator<[number, number]>;
+  /**
+   * @method values
+   * @description 获取迭代器
+   * @returns {IterableIterator<number>}
+   */
+  values(): IterableIterator<number>;
+  /**
+   * @method iterator
+   * @description 迭代器
+   * @returns {IterableIterator<number>}
+   */
+  [Symbol.iterator](): IterableIterator<number>;
   /**
    * @override
    * @method toString

package/cjs/{Binary.cjs → binary.cjs}

@@ -1,7 +1,7 @@
 /**
  * @package @nuintun/buffer
  * @license MIT
- * @version 0.3.2
+ * @version 0.5.0
  * @author nuintun <nuintun@qq.com>
  * @description A buffer tool for javascript.
  * @see https://github.com/nuintun/Buffer#readme
@@ -10,7 +10,7 @@
 'use strict';
 
 /**
- * @module Binary
+ * @module binary
  */
 /**
  * @type {string[]}

package/{esm/Binary.d.ts → cjs/binary.d.cts}

@@ -1,5 +1,5 @@
 /**
- * @module Binary
+ * @module binary
  */
 /**
  * @type {string[]}

package/cjs/encoding.cjs

@@ -0,0 +1,94 @@
+/**
+ * @package @nuintun/buffer
+ * @license MIT
+ * @version 0.5.0
+ * @author nuintun <nuintun@qq.com>
+ * @description A buffer tool for javascript.
+ * @see https://github.com/nuintun/Buffer#readme
+ */
+
+'use strict';
+
+const errors = require('./errors.cjs');
+
+/**
+ * @module encoding
+ */
+/**
+ * @function encodeSBSC
+ * @description 单字节字符编码
+ * @param {string} content 文本内容
+ * @param {number} maxCode 最大编码
+ * @returns {Uint8Array}
+ */
+function encodeSBSC(content, maxCode) {
+  const bytes = [];
+  for (const character of content) {
+    const code = character.codePointAt(0);
+    // If gt max code, push "?".
+    bytes.push(code == null || code > maxCode ? 63 : code);
+  }
+  return new Uint8Array(bytes);
+}
+/**
+ * @function swapEndian
+ * @description 翻转字节序
+ * @param {number} value 待翻转字节序的值
+ * @returns {number}
+ */
+function swapEndian(value) {
+  return ((value & 0xff) << 8) | ((value >> 8) & 0xff);
+}
+/**
+ * @function encodeUTF16
+ * @param {string} input 待编码字符串
+ * @param {boolean} [littleEndian] 是否使用小端字节序
+ * @returns {Uint8Array}
+ */
+function encodeUTF16(input, littleEndian) {
+  let offset = 0;
+  // 分配内存
+  const codes = new Uint16Array(input.length);
+  for (const char of input) {
+    const code = char.codePointAt(0);
+    if (code > 0xffff) {
+      // 代理对处理
+      const high = 0xd800 | ((code - 0x10000) >> 10);
+      const low = 0xdc00 | (code & 0x3ff);
+      codes[offset++] = littleEndian ? high : swapEndian(high);
+      codes[offset++] = littleEndian ? low : swapEndian(low);
+    } else {
+      codes[offset++] = littleEndian ? code : swapEndian(code);
+    }
+  }
+  return new Uint8Array(codes.buffer, 0, offset * 2);
+}
+function encode(content, encoding) {
+  switch (encoding.toLowerCase()) {
+    case 'ascii':
+      return encodeSBSC(content, 0x7f);
+    case 'latin1':
+      return encodeSBSC(content, 0xff);
+    case 'utf8':
+    case 'utf-8':
+      return new TextEncoder().encode(content);
+    case 'utf16le':
+    case 'utf-16le':
+      return encodeUTF16(content, true);
+    case 'utf16be':
+    case 'utf-16be':
+      return encodeUTF16(content, false);
+    default:
+      throw new Error(errors.encodingInvalid(encoding));
+  }
+}
+function decode(bytes, encoding) {
+  try {
+    return new TextDecoder(encoding).decode(bytes);
+  } catch {
+    throw new Error(errors.encodingInvalid(encoding));
+  }
+}
+
+exports.decode = decode;
+exports.encode = encode;

package/cjs/encoding.d.cts

@@ -0,0 +1,25 @@
+/**
+ * @module encoding
+ */
+export interface TextEncode {
+  /**
+   * @function encode
+   * @description 用指定编码编码字符串
+   * @param {string} content 待编码文本
+   * @param {string} encoding 编码类型
+   * @returns {Uint8Array}
+   */
+  (content: string, encoding: string): Uint8Array;
+}
+export interface TextDecode {
+  /**
+   * @function decode
+   * @description 用指定编码解码字节数组
+   * @param {Uint8Array} bytes 待解码字节数组
+   * @param {string} encoding 编码类型
+   * @returns {string}
+   */
+  (bytes: Uint8Array, encoding: string): string;
+}
+export declare function encode(content: string, encoding: string): Uint8Array;
+export declare function decode(bytes: Uint8Array, encoding: string): string;

package/cjs/enum.cjs

@@ -1,7 +1,7 @@
 /**
  * @package @nuintun/buffer
  * @license MIT
- * @version 0.3.2
+ * @version 0.5.0
  * @author nuintun <nuintun@qq.com>
  * @description A buffer tool for javascript.
  * @see https://github.com/nuintun/Buffer#readme

package/cjs/errors.cjs

@@ -1,7 +1,7 @@
 /**
  * @package @nuintun/buffer
  * @license MIT
- * @version 0.3.2
+ * @version 0.5.0
  * @author nuintun <nuintun@qq.com>
  * @description A buffer tool for javascript.
  * @see https://github.com/nuintun/Buffer#readme
@@ -15,7 +15,7 @@
 /**
  * @function encodingInvalid
  * @description 未支持的编码格式
- * @param encoding 编码格式
+ * @param {string} encoding 编码格式
  */
 function encodingInvalid(encoding) {
   return 'unsupported encoding ' + encoding;

package/cjs/errors.d.cts

@@ -4,7 +4,7 @@
 /**
  * @function encodingInvalid
  * @description 未支持的编码格式
- * @param encoding 编码格式
+ * @param {string} encoding 编码格式
  */
 export declare function encodingInvalid(encoding: string): string;
 export declare const offsetInvalid = 'invalid buffer offset';

package/cjs/index.cjs

@@ -1,7 +1,7 @@
 /**
  * @package @nuintun/buffer
  * @license MIT
- * @version 0.3.2
+ * @version 0.5.0
  * @author nuintun <nuintun@qq.com>
  * @description A buffer tool for javascript.
  * @see https://github.com/nuintun/Buffer#readme
@@ -9,10 +9,10 @@
 
 'use strict';
 
-const Binary = require('./Binary.cjs');
 const errors = require('./errors.cjs');
-const index = require('./Encoding/index.cjs');
+const binary = require('./binary.cjs');
 const _enum = require('./enum.cjs');
+const encoding = require('./encoding.cjs');
 const utils = require('./utils.cjs');
 
 /**
@@ -49,14 +49,14 @@ class Buffer {
   #offset = 0;
   // 已使用字节长度
   #length = 0;
-  /**
-   * @constructor
-   * @param {number | Uint8Array | ArrayBuffer} [input] 缓冲区初始配置
-   * @param {number} [pageSize] 缓冲区分页大小，扩容时将按分页大小增加
-   */
-  constructor(input = 0, pageSize = 4096) {
+  // 文本编码方法
+  #encode;
+  // 文本解码方法
+  #decode;
+  constructor(input = 0, options = {}) {
     let length;
     let bytes;
+    const { pageSize = 4096 } = options;
     if (utils.isTypedArray(input)) {
       length = input.byteLength;
       bytes = utils.makeUint8Array(length, pageSize);
@@ -76,6 +76,8 @@ class Buffer {
     this.#bytes = bytes;
     this.#length = length;
     this.#pageSize = pageSize;
+    this.#encode = options.encode ?? encoding.encode;
+    this.#decode = options.decode ?? encoding.decode;
     this.#dataView = new DataView(bytes.buffer);
   }
   /**
@@ -329,7 +331,7 @@ class Buffer {
     if (input instanceof Uint8Array) {
       bytes = input.subarray(start, end);
     } else {
-      bytes = index.encode(input, start);
+      bytes = this.#encode(input, start ?? 'utf-8');
     }
     const { length } = bytes;
     if (length > 0) {
@@ -483,8 +485,8 @@ class Buffer {
     this.#assertRead(offset);
     const bytes = this.#bytes.slice(this.#offset, offset);
     this.#seek(offset);
-    if (arguments.length >= 2) {
-      return index.decode(bytes, encoding);
+    if (encoding != null) {
+      return this.#decode(bytes, encoding);
     }
     return bytes;
   }
@@ -497,8 +499,11 @@ class Buffer {
    * @returns {Buffer}
    */
   slice(start, end) {
-    const bytes = this.#bytes.slice(start, end);
-    return new Buffer(bytes, this.#pageSize);
+    return new Buffer(this.bytes.slice(start, end), {
+      encode: this.#encode,
+      decode: this.#decode,
+      pageSize: this.#pageSize
+    });
   }
   /**
    * @public
@@ -510,7 +515,7 @@ class Buffer {
    * @returns {this}
    */
   copyWithin(target, start, end) {
-    this.#bytes.copyWithin(target, start, end);
+    this.bytes.copyWithin(target, start, end);
     return this;
   }
   /**
@@ -537,6 +542,14 @@ class Buffer {
       yield bytes[i];
     }
   }
+  /**
+   * @method iterator
+   * @description 迭代器
+   * @returns {IterableIterator<number>}
+   */
+  [Symbol.iterator]() {
+    return this.values();
+  }
   /**
    * @override
    * @method toString
@@ -545,23 +558,13 @@ class Buffer {
    */
   toString() {
     // 二进制编码字符串
-    let binary = '';
-    // 提前获取 bytes，防止重复计算
-    const bytes = this.bytes;
+    let binary$1 = '';
     // 获取二进制编码
-    for (const byte of bytes) {
-      binary += Binary.mapping[byte];
+    for (const byte of this) {
+      binary$1 += binary.mapping[byte];
     }
     // 返回二进制编码
-    return binary;
-  }
-  /**
-   * @method iterator
-   * @description 迭代器
-   * @returns {IterableIterator<number>}
-   */
-  [Symbol.iterator]() {
-    return this.values();
+    return binary$1;
   }
 }