@nuintun/buffer 0.3.1 → 0.4.0

package/cjs/index.cjs

@@ -1,7 +1,7 @@
 /**
  * @package @nuintun/buffer
  * @license MIT
- * @version 0.3.1
+ * @version 0.4.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');
 
 /**
@@ -24,10 +24,10 @@ const utils = require('./utils.cjs');
  * @returns {Endian}
  */
 function endianness() {
-  switch (new Uint8Array(new Uint32Array([0x12345678]))[0]) {
-    case 0x12:
+  switch (new Uint8Array(new Uint16Array([0x00ff]).buffer)[0]) {
+    case 0x00:
       return _enum.Endian.Big;
-    case 0x78:
+    case 0xff:
       return _enum.Endian.Little;
     default:
       throw new TypeError(errors.unknownEndianness);
@@ -49,29 +49,36 @@ class Buffer {
   #offset = 0;
   // 已使用字节长度
   #length = 0;
-  /**
-   * @constructor
-   * @param {number | Uint8Array} input 缓冲区初始配置
-   * @param {number} pageSize 缓冲区分页大小，扩容时将按分页大小增加
-   */
-  constructor(input = 0, pageSize = 4096) {
+  // 文本编码方法
+  #encode;
+  // 文本解码方法
+  #decode;
+  constructor(input = 0, options = {}) {
     let length;
     let bytes;
-    let dataView;
-    if (input instanceof Uint8Array) {
-      length = input.length;
+    const { pageSize = 4096 } = options;
+    if (utils.isTypedArray(input)) {
+      length = input.byteLength;
       bytes = utils.makeUint8Array(length, pageSize);
-      bytes.set(input);
-      dataView = new DataView(bytes.buffer);
+      if (length > 0) {
+        bytes.set(new Uint8Array(input.buffer));
+      }
+    } else if (input instanceof ArrayBuffer) {
+      length = input.byteLength;
+      bytes = utils.makeUint8Array(length, pageSize);
+      if (length > 0) {
+        bytes.set(new Uint8Array(input));
+      }
     } else {
       length = input;
-      bytes = utils.makeUint8Array(input, pageSize);
-      dataView = new DataView(bytes.buffer);
+      bytes = utils.makeUint8Array(length, pageSize);
     }
     this.#bytes = bytes;
     this.#length = length;
-    this.#dataView = dataView;
     this.#pageSize = pageSize;
+    this.#encode = options.encode ?? encoding.encode;
+    this.#decode = options.decode ?? encoding.decode;
+    this.#dataView = new DataView(bytes.buffer);
   }
   /**
    * @private
@@ -176,16 +183,16 @@ class Buffer {
   /**
    * @public
    * @property {ArrayBuffer} buffer
-   * @description 获取 ArrayBuffer 缓冲区
+   * @description 获取全部 ArrayBuffer 原始缓冲区
    * @returns {ArrayBuffer}
    */
   get buffer() {
-    return this.bytes.buffer;
+    return this.#bytes.buffer;
   }
   /**
    * @public
    * @property {Uint8Array} bytes
-   * @description 获取 Uint8Array 缓冲区
+   * @description 获取已写入 Uint8Array 原始缓冲区
    * @returns {Uint8Array}
    */
   get bytes() {
@@ -324,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) {
@@ -478,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;
   }
@@ -492,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
@@ -508,6 +518,38 @@ class Buffer {
     this.#bytes.copyWithin(target, start, end);
     return this;
   }
+  /**
+   * @method entries
+   * @description 获取迭代器
+   * @returns {IterableIterator<[number, number]>}
+   */
+  *entries() {
+    const bytes = this.bytes;
+    const length = this.#length;
+    for (let i = 0; i < length; i++) {
+      yield [i, bytes[i]];
+    }
+  }
+  /**
+   * @method values
+   * @description 获取迭代器
+   * @returns {IterableIterator<number>}
+   */
+  *values() {
+    const bytes = this.bytes;
+    const length = this.#length;
+    for (let i = 0; i < length; i++) {
+      yield bytes[i];
+    }
+  }
+  /**
+   * @method iterator
+   * @description 迭代器
+   * @returns {IterableIterator<number>}
+   */
+  [Symbol.iterator]() {
+    return this.values();
+  }
   /**
    * @override
    * @method toString
@@ -516,15 +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;
+    return binary$1;
   }
 }
 

package/cjs/index.d.cts

@@ -1,8 +1,28 @@
 /**
  * @module Buffer
  */
+import type { TypedArray } from './utils.cjs';
 import { Endian } from './enum.cjs';
+import { TextDecode, TextEncode } from './encoding.cjs';
 export { Endian };
+export type { TypedArray };
+export interface Options {
+  /**
+   * @property {number} [pageSize]
+   * @description 缓存页大小
+   */
+  pageSize?: number;
+  /**
+   * @property {TextEncode} [encode]
+   * @description 文本编码函数
+   */
+  encode?: TextEncode;
+  /**
+   * @property {TextDecode} [decode]
+   * @description 文本解码函数
+   */
+  decode?: TextDecode;
+}
 /**
  * @function endianness
  * @description 获取系统默认字节序
@@ -17,16 +37,22 @@ export declare class Buffer {
   #private;
   /**
    * @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
@@ -59,14 +85,14 @@ export declare class Buffer {
   /**
    * @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;
@@ -269,6 +295,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/utils.cjs

@@ -1,7 +1,7 @@
 /**
  * @package @nuintun/buffer
  * @license MIT
- * @version 0.3.1
+ * @version 0.4.0
  * @author nuintun <nuintun@qq.com>
  * @description A buffer tool for javascript.
  * @see https://github.com/nuintun/Buffer#readme
@@ -12,6 +12,17 @@
 /**
  * @module utils
  */
+// 获取 TypedArray 原型
+const TypedArray = Object.getPrototypeOf(Uint8Array);
+/**
+ * @function isTypedArray
+ * @description 检测是否为 TypedArray
+ * @param value 待判断的值
+ * @returns {boolean}
+ */
+function isTypedArray(value) {
+  return value instanceof TypedArray;
+}
 /**
  * @function isNaturalNumber
  * @description 判断是否为自然数
@@ -19,21 +30,22 @@
  * @returns {boolean}
  */
 function isNaturalNumber(value) {
-  return value >= 0 && Number.isInteger(value);
+  return Number.isInteger(value) && value >= 0;
 }
 /**
  * @function makeUint8Array
  * @description 创建一个合适长度的 Uint8Array
- * @param {number} byteLength 数据字节总大小
+ * @param {number} length 数据长度大小
  * @param {number} pageSize 缓冲区页大小
  * @returns {Uint8Array}
  */
-function makeUint8Array(byteLength, pageSize) {
-  if (byteLength > pageSize) {
-    return new Uint8Array(Math.ceil(byteLength / pageSize) * pageSize);
+function makeUint8Array(length, pageSize) {
+  if (length > pageSize) {
+    return new Uint8Array(Math.ceil(length / pageSize) * pageSize);
   }
   return new Uint8Array(pageSize);
 }
 
 exports.isNaturalNumber = isNaturalNumber;
+exports.isTypedArray = isTypedArray;
 exports.makeUint8Array = makeUint8Array;

package/cjs/utils.d.cts

@@ -1,18 +1,37 @@
 /**
  * @module utils
  */
+export type TypedArray =
+  | Int8Array
+  | Int16Array
+  | Int32Array
+  | Uint8Array
+  | Uint16Array
+  | Uint32Array
+  | Float32Array
+  | Float64Array
+  | BigInt64Array
+  | BigUint64Array
+  | Uint8ClampedArray;
+/**
+ * @function isTypedArray
+ * @description 检测是否为 TypedArray
+ * @param value 待判断的值
+ * @returns {boolean}
+ */
+export declare function isTypedArray(value: unknown): value is TypedArray;
 /**
  * @function isNaturalNumber
  * @description 判断是否为自然数
  * @param value 待判断的值
  * @returns {boolean}
  */
-export declare function isNaturalNumber(value: number): boolean;
+export declare function isNaturalNumber(value: unknown): value is number;
 /**
  * @function makeUint8Array
  * @description 创建一个合适长度的 Uint8Array
- * @param {number} byteLength 数据字节总大小
+ * @param {number} length 数据长度大小
  * @param {number} pageSize 缓冲区页大小
  * @returns {Uint8Array}
  */
-export declare function makeUint8Array(byteLength: number, pageSize: number): Uint8Array;
+export declare function makeUint8Array(length: number, pageSize: number): Uint8Array;

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

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

package/esm/{Binary.js → binary.js}

@@ -1,14 +1,14 @@
 /**
  * @package @nuintun/buffer
  * @license MIT
- * @version 0.3.1
+ * @version 0.4.0
  * @author nuintun <nuintun@qq.com>
  * @description A buffer tool for javascript.
  * @see https://github.com/nuintun/Buffer#readme
  */
 
 /**
- * @module Binary
+ * @module binary
  */
 /**
  * @type {string[]}

package/esm/encoding.d.ts

@@ -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/esm/encoding.js

@@ -0,0 +1,91 @@
+/**
+ * @package @nuintun/buffer
+ * @license MIT
+ * @version 0.4.0
+ * @author nuintun <nuintun@qq.com>
+ * @description A buffer tool for javascript.
+ * @see https://github.com/nuintun/Buffer#readme
+ */
+
+import { encodingInvalid } from './errors.js';
+
+/**
+ * @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(encodingInvalid(encoding));
+  }
+}
+function decode(bytes, encoding) {
+  try {
+    return new TextDecoder(encoding).decode(bytes);
+  } catch {
+    throw new Error(encodingInvalid(encoding));
+  }
+}
+
+export { decode, encode };

package/esm/enum.js

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

package/esm/errors.d.ts

@@ -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/esm/errors.js

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

package/esm/index.d.ts

@@ -1,8 +1,28 @@
 /**
  * @module Buffer
  */
+import type { TypedArray } from './utils.js';
 import { Endian } from './enum.js';
+import { TextDecode, TextEncode } from './encoding.js';
 export { Endian };
+export type { TypedArray };
+export interface Options {
+  /**
+   * @property {number} [pageSize]
+   * @description 缓存页大小
+   */
+  pageSize?: number;
+  /**
+   * @property {TextEncode} [encode]
+   * @description 文本编码函数
+   */
+  encode?: TextEncode;
+  /**
+   * @property {TextDecode} [decode]
+   * @description 文本解码函数
+   */
+  decode?: TextDecode;
+}
 /**
  * @function endianness
  * @description 获取系统默认字节序
@@ -17,16 +37,22 @@ export declare class Buffer {
   #private;
   /**
    * @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
@@ -59,14 +85,14 @@ export declare class Buffer {
   /**
    * @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;
@@ -269,6 +295,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