@nuintun/buffer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 nuintun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,310 @@
+# Buffer
+
+<!-- prettier-ignore -->
+> A buffer tool for javascript.
+>
+> [![NPM Version][npm-image]][npm-url]
+> [![Download Status][download-image]][npm-url]
+> [![Languages Status][languages-image]][github-url]
+> [![Tree Shakeable][tree-shakeable-image]][bundle-phobia-url]
+> [![Side Effect][side-effect-image]][bundle-phobia-url]
+> [![License][license-image]][license-url]
+
+### Usage
+
+##### Common Interface
+
+```ts
+/**
+ * @module Buffer
+ */
+export declare enum Endian {
+  Big = 0,
+  Little = 1
+}
+/**
+ * @function endianness
+ * @description 获取系统默认字节序
+ * @returns {Endian}
+ */
+export declare function endianness(): Endian;
+/**
+ * @class Buffer
+ * @classdesc Buffer 类提供用于优化读取，写入以及处理二进制数据的方法和属性
+ */
+export declare class Buffer {
+  #private;
+  /**
+   * @constructor
+   * @param {number} [length] 缓冲区初始大小
+   * @param {number} [pageSize] 缓冲区分页大小，扩容时将按分页大小增加
+   */
+  constructor(length?: number, pageSize?: number);
+  /**
+   * @constructor
+   * @param {Uint8Array} bytes 缓冲区初始数据
+   * @param {number} [pageSize] 缓冲区分页大小，扩容时将按分页大小增加
+   */
+  constructor(bytes?: Uint8Array, pageSize?: number);
+  /**
+   * @public
+   * @property {number} offset
+   * @description 设置读写指针位置，以字节为单位
+   * @description 下一次调用读写方法时将在此位置开始读写
+   */
+  set offset(offset: number);
+  /**
+   * @public
+   * @property {number} offset
+   * @description 获取读写指针的位置
+   * @returns {number}
+   */
+  get offset(): number;
+  /**
+   * @public
+   * @property {number} length
+   * @description 设置 Buffer 长度
+   * @description 如果将长度设置为小于当前长度的值，将会截断该字节数组
+   * @description 如果将长度设置为大于当前长度的值，则用零填充字节数组的右侧
+   */
+  set length(length: number);
+  /**
+   * @public
+   * @property {number} length
+   * @description 获取 Buffer 长度
+   * @returns {number}
+   */
+  get length(): number;
+  /**
+   * @public
+   * @property {ArrayBuffer} buffer
+   * @description 获取 ArrayBuffer 缓冲区
+   * @returns {ArrayBuffer}
+   */
+  get buffer(): ArrayBuffer;
+  /**
+   * @public
+   * @property {Uint8Array} bytes
+   * @description 获取 Uint8Array 缓冲区
+   * @returns {Uint8Array}
+   */
+  get bytes(): Uint8Array;
+  /**
+   * @public
+   * @method writeInt8
+   * @description 在缓冲区中写入一个有符号整数
+   * @param {number} value 介于 -128 和 127 之间的整数
+   */
+  writeInt8(value: number): void;
+  /**
+   * @public
+   * @method writeUint8
+   * @description 在缓冲区中写入一个无符号整数
+   * @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 位有符号整数
+   * @param {number} value 要写入的 16 位有符号整数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   */
+  writeInt16(value: number, littleEndian?: boolean): void;
+  /**
+   * @method writeUint16
+   * @description 在缓冲区中写入一个 16 位无符号整数
+   * @param {number} value 要写入的 16 位无符号整数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   */
+  writeUint16(value: number, littleEndian?: boolean): void;
+  /**
+   * @method writeInt32
+   * @description 在缓冲区中写入一个有符号的 32 位有符号整数
+   * @param {number} value 要写入的 32 位有符号整数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   */
+  writeInt32(value: number, littleEndian?: boolean): void;
+  /**
+   * @method writeUint32
+   * @description 在缓冲区中写入一个无符号的 32 位无符号整数
+   * @param {number} value 要写入的 32 位无符号整数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   */
+  writeUint32(value: number, littleEndian?: boolean): void;
+  /**
+   * @method writeInt64
+   * @description 在缓冲区中写入一个无符号的 64 位有符号整数
+   * @param {bigint} value 要写入的 32 位有符号整数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   */
+  writeInt64(value: bigint, littleEndian?: boolean): void;
+  /**
+   * @method writeUint64
+   * @description 在缓冲区中写入一个无符号的 64 位无符号整数
+   * @param {bigint} value 要写入的 64 位无符号整数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   */
+  writeUint64(value: bigint, littleEndian?: boolean): void;
+  /**
+   * @method writeFloat32
+   * @description 在缓冲区中写入一个 IEEE 754 单精度 32 位浮点数
+   * @param {number} value 单精度 32 位浮点数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   */
+  writeFloat32(value: number, littleEndian?: boolean): void;
+  /**
+   * @method writeFloat64
+   * @description 在缓冲区中写入一个 IEEE 754 双精度 64 位浮点数
+   * @param {number} value 双精度 64 位浮点数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   */
+  writeFloat64(value: number, littleEndian?: boolean): void;
+  /**
+   * @method write
+   * @description 将字符串用指定编码写入字节流
+   * @param {string} value 要写入的字符串
+   * @param {string} [encoding] 字符串编码
+   */
+  write(value: string, encoding?: string): void;
+  /**
+   * @method write
+   * @description 将 Uint8Array 对象写入字节流
+   * @param {Uint8Array} bytes 要写入 Uint8Array 对象
+   * @param {number} [start] Uint8Array 对象开始索引
+   * @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 位有符号整数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   * @returns {number} 介于 -32768 和 32767 之间的 16 位有符号整数
+   */
+  readInt16(littleEndian?: boolean): number;
+  /**
+   * @method readUint16
+   * @description 从缓冲区中读取一个 16 位无符号整数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   * @returns {number} 介于 0 和 65535 之间的 16 位无符号整数
+   */
+  readUint16(littleEndian?: boolean): number;
+  /**
+   * @method readInt32
+   * @description 从缓冲区中读取一个 32 位有符号整数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   * @returns {number} 介于 -2147483648 和 2147483647 之间的 32 位有符号整数
+   */
+  readInt32(littleEndian?: boolean): number;
+  /**
+   * @method readUint32
+   * @description 从缓冲区中读取一个 32 位无符号整数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   * @returns {number} 介于 0 和 4294967295 之间的 32 位无符号整数
+   */
+  readUint32(littleEndian?: boolean): number;
+  /**
+   * @method readInt64
+   * @description 从缓冲区中读取一个 64 位有符号整数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   * @returns {bigint} 介于 -9223372036854775808 和 9223372036854775807 之间的 64 位有符号整数
+   */
+  readInt64(littleEndian?: boolean): bigint;
+  /**
+   * @method readUint64
+   * @description 从缓冲区中读取一个 64 位无符号整数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   * @returns {bigint} 介于 0 和 18446744073709551615 之间的 64 位无符号整数
+   */
+  readUint64(littleEndian?: boolean): bigint;
+  /**
+   * @method readFloat32
+   * @description 从缓冲区中读取一个 IEEE 754 单精度 32 位浮点数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   * @returns {number} 单精度 32 位浮点数
+   */
+  readFloat32(littleEndian?: boolean): number;
+  /**
+   * @method readFloat64
+   * @description 从缓冲区中读取一个 IEEE 754 双精度 64 位浮点数
+   * @param {boolean} [littleEndian] 是否为小端字节序
+   * @returns {number} 双精度 64 位浮点数
+   */
+  readFloat64(littleEndian?: boolean): number;
+  /**
+   * @method read
+   * @description 从缓冲区中读取指定长度的 Uint8Array 对象
+   * @param {number} length 读取的字节长度
+   * @returns {Uint8Array}
+   */
+  read(length: number): Uint8Array;
+  /**
+   * @method read
+   * @description 从缓冲区中读取一个字符串
+   * @param {number} length 读取的字节长度
+   * @param {string} encoding 字符串编码
+   * @returns {string} 指定编码的字符串
+   */
+  read(length: number, encoding: string): string;
+  /**
+   * @public
+   * @method slice
+   * @description 从指定开始和结束位置索引截取并返回新的 Buffer 对象
+   * @param {number} [start] 截取开始位置索引
+   * @param {number} [end] 截取结束位置索引
+   * @returns {Buffer}
+   */
+  slice(start?: number, end?: number): Buffer;
+  /**
+   * @public
+   * @method copyWithin
+   * @description 从 Buffer 对象中将指定位置的数据复制到以 target 起始的位置
+   * @param {number} target 粘贴开始位置索引
+   * @param {number} start 复制开始位置索引
+   * @param {number} [end] 复制结束位置索引
+   * @returns {this}
+   */
+  copyWithin(target: number, start: number, end?: number): this;
+  /**
+   * @override
+   * @method toString
+   * @description 获取 Buffer 对象二进制编码字符串
+   * @returns {string}
+   */
+  toString(): string;
+}
+```
+
+[npm-image]: https://img.shields.io/npm/v/@nuintun/buffer?style=flat-square
+[npm-url]: https://www.npmjs.org/package/@nuintun/buffer
+[download-image]: https://img.shields.io/npm/dm/@nuintun/buffer?style=flat-square
+[languages-image]: https://img.shields.io/github/languages/top/nuintun/buffer?style=flat-square
+[github-url]: https://github.com/nuintun/buffer
+[tree-shakeable-image]: https://img.shields.io/badge/tree--shakeable-true-brightgreen?style=flat-square
+[side-effect-image]: https://img.shields.io/badge/side--effect-free-brightgreen?style=flat-square
+[bundle-phobia-url]: https://bundlephobia.com/result?p=@nuintun/buffer
+[license-image]: https://img.shields.io/github/license/nuintun/buffer?style=flat-square
+[license-url]: https://github.com/nuintun/buffer/blob/main/LICENSE

package/cjs/Binary.cjs

@@ -0,0 +1,25 @@
+/**
+ * @package @nuintun/buffer
+ * @license MIT
+ * @version 0.1.0
+ * @author nuintun <nuintun@qq.com>
+ * @description A buffer tool for javascript.
+ * @see https://github.com/nuintun/Buffer#readme
+ */
+
+'use strict';
+
+/**
+ * @module Binary
+ */
+/**
+ * @type {string[]}
+ * @description 已获得的二进制映射表
+ */
+const mapping = [];
+// 生成映射表
+for (let code = 0; code < 256; code++) {
+  mapping[code] = String.fromCharCode(code);
+}
+
+exports.mapping = mapping;

package/cjs/Binary.d.cts

@@ -0,0 +1,8 @@
+/**
+ * @module Binary
+ */
+/**
+ * @type {string[]}
+ * @description 已获得的二进制映射表
+ */
+export declare const mapping: string[];

package/cjs/Encoding/UTF8.cjs

@@ -0,0 +1,33 @@
+/**
+ * @package @nuintun/buffer
+ * @license MIT
+ * @version 0.1.0
+ * @author nuintun <nuintun@qq.com>
+ * @description A buffer tool for javascript.
+ * @see https://github.com/nuintun/Buffer#readme
+ */
+
+'use strict';
+
+/**
+ * @module UTF8
+ */
+// 编码器实例
+const encoder = new TextEncoder();
+// 解码器实例
+const decoder = new TextDecoder();
+/**
+ * @function encode
+ * @param {string} input
+ * @returns {Uint8Array}
+ */
+const encode = encoder.encode.bind(encoder);
+/**
+ * @function decode
+ * @param {BufferSource} input
+ * @returns {string}
+ */
+const decode = decoder.decode.bind(decoder);
+
+exports.decode = decode;
+exports.encode = encode;

package/cjs/Encoding/UTF8.d.cts

@@ -0,0 +1,15 @@
+/**
+ * @module UTF8
+ */
+/**
+ * @function encode
+ * @param {string} input
+ * @returns {Uint8Array}
+ */
+export declare const encode: (input?: string) => Uint8Array;
+/**
+ * @function decode
+ * @param {BufferSource} input
+ * @returns {string}
+ */
+export declare const decode: (input?: BufferSource) => string;

package/cjs/Encoding/Unicode.cjs

@@ -0,0 +1,45 @@
+/**
+ * @package @nuintun/buffer
+ * @license MIT
+ * @version 0.1.0
+ * @author nuintun <nuintun@qq.com>
+ * @description A buffer tool for javascript.
+ * @see https://github.com/nuintun/Buffer#readme
+ */
+
+'use strict';
+
+/**
+ * @module Unicode
+ */
+/**
+ * @function encode
+ * @param {string} input
+ * @param {TypeArray} Buffer
+ * @returns {Uint8Array}
+ */
+function encode(input, TypeArray) {
+  const { length } = input;
+  const array = new TypeArray(length);
+  for (let i = 0; i < length; i++) {
+    array[i] = input.codePointAt(i) || 0;
+  }
+  return new Uint8Array(array.buffer);
+}
+/**
+ * @function decode
+ * @param {BufferSource} input
+ * @param {TypeArray} Buffer
+ * @returns {string}
+ */
+function decode(input, TypeArray) {
+  let result = '';
+  const array = new TypeArray(ArrayBuffer.isView(input) ? input.buffer : input);
+  for (const code of array) {
+    result += String.fromCodePoint(code);
+  }
+  return result;
+}
+
+exports.decode = decode;
+exports.encode = encode;

package/cjs/Encoding/Unicode.d.cts

@@ -0,0 +1,18 @@
+/**
+ * @module Unicode
+ */
+export type TypeArray = typeof Uint16Array | typeof Uint32Array;
+/**
+ * @function encode
+ * @param {string} input
+ * @param {TypeArray} Buffer
+ * @returns {Uint8Array}
+ */
+export declare function encode(input: string, TypeArray: TypeArray): Uint8Array;
+/**
+ * @function decode
+ * @param {BufferSource} input
+ * @param {TypeArray} Buffer
+ * @returns {string}
+ */
+export declare function decode(input: BufferSource, TypeArray: TypeArray): string;

package/cjs/Encoding/index.cjs

@@ -0,0 +1,65 @@
+/**
+ * @package @nuintun/buffer
+ * @license MIT
+ * @version 0.1.0
+ * @author nuintun <nuintun@qq.com>
+ * @description A buffer tool for javascript.
+ * @see https://github.com/nuintun/Buffer#readme
+ */
+
+'use strict';
+
+const UTF8 = require('./UTF8.cjs');
+const errors = require('../errors.cjs');
+const Unicode = require('./Unicode.cjs');
+
+/**
+ * @module Encoding
+ */
+/**
+ * @function encode
+ * @description 用指定编码编码字符串
+ * @param {string} input 需要编码的字符串
+ * @param {string} [encoding] 字符串编码
+ * @returns {Uint8Array}
+ */
+function encode(input, encoding = 'UTF8') {
+  switch (encoding.toUpperCase()) {
+    case 'UTF8':
+    case 'UTF-8':
+      return UTF8.encode(input);
+    case 'UTF16':
+    case 'UTF-16':
+      return Unicode.encode(input, Uint16Array);
+    case 'UTF32':
+    case 'UTF-32':
+      return Unicode.encode(input, Uint32Array);
+    default:
+      throw new TypeError(errors.encodingInvalid(encoding));
+  }
+}
+/**
+ * @function decode
+ * @description 用指定编码解码字符串数据
+ * @param {BufferSource} input 需要解码的字符串数据
+ * @param {string} [encoding] 字符串编码
+ * @returns {string}
+ */
+function decode(input, encoding = 'UTF8') {
+  switch (encoding.toUpperCase()) {
+    case 'UTF8':
+    case 'UTF-8':
+      return UTF8.decode(input);
+    case 'UTF16':
+    case 'UTF-16':
+      return Unicode.decode(input, Uint16Array);
+    case 'UTF32':
+    case 'UTF-32':
+      return Unicode.decode(input, Uint32Array);
+    default:
+      throw new TypeError(errors.encodingInvalid(encoding));
+  }
+}
+
+exports.decode = decode;
+exports.encode = encode;

package/cjs/Encoding/index.d.cts

@@ -0,0 +1,19 @@
+/**
+ * @module Encoding
+ */
+/**
+ * @function encode
+ * @description 用指定编码编码字符串
+ * @param {string} input 需要编码的字符串
+ * @param {string} [encoding] 字符串编码
+ * @returns {Uint8Array}
+ */
+export declare function encode(input: string, encoding?: string): Uint8Array;
+/**
+ * @function decode
+ * @description 用指定编码解码字符串数据
+ * @param {BufferSource} input 需要解码的字符串数据
+ * @param {string} [encoding] 字符串编码
+ * @returns {string}
+ */
+export declare function decode(input: BufferSource, encoding?: string): string;

package/cjs/enum.d.cts

@@ -0,0 +1,15 @@
+/**
+ * @module enum
+ */
+export declare const enum SizeOf {
+  INT8 = 1,
+  UINT8 = 1,
+  INT16 = 2,
+  UINT16 = 2,
+  INT32 = 4,
+  UINT32 = 4,
+  INI64 = 8,
+  UINT64 = 8,
+  FLOAT32 = 4,
+  FLOAT64 = 8
+}

package/cjs/errors.cjs

@@ -0,0 +1,35 @@
+/**
+ * @package @nuintun/buffer
+ * @license MIT
+ * @version 0.1.0
+ * @author nuintun <nuintun@qq.com>
+ * @description A buffer tool for javascript.
+ * @see https://github.com/nuintun/Buffer#readme
+ */
+
+'use strict';
+
+/**
+ * @module errors
+ */
+// 未支持的编码格式
+function encodingInvalid(encoding) {
+  return 'unsupported encoding ' + encoding;
+}
+// 未知字节序
+const unknownEndianness = 'unknown endianness';
+// 非法长度
+const lengthInvalid = 'invalid buffer length';
+// 非法读写指针
+const offsetInvalid = 'invalid buffer offset';
+// 数据读取溢出
+const readOverflow = 'read is outside the bounds of the Buffer';
+// 读写指针溢出
+const offsetOverflow = 'offset is outside the bounds of the Buffer';
+
+exports.encodingInvalid = encodingInvalid;
+exports.lengthInvalid = lengthInvalid;
+exports.offsetInvalid = offsetInvalid;
+exports.offsetOverflow = offsetOverflow;
+exports.readOverflow = readOverflow;
+exports.unknownEndianness = unknownEndianness;

package/cjs/errors.d.cts

@@ -0,0 +1,9 @@
+/**
+ * @module errors
+ */
+export declare function encodingInvalid(encoding: string): string;
+export declare const unknownEndianness = 'unknown endianness';
+export declare const lengthInvalid = 'invalid buffer length';
+export declare const offsetInvalid = 'invalid buffer offset';
+export declare const readOverflow = 'read is outside the bounds of the Buffer';
+export declare const offsetOverflow = 'offset is outside the bounds of the Buffer';