@nuintun/buffer 0.1.0

package/cjs/index.d.cts

@@ -0,0 +1,281 @@
+/**
+ * @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;
+}

package/cjs/utils.cjs

@@ -0,0 +1,31 @@
+/**
+ * @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 utils
+ */
+/**
+ * @function calcBufferLength
+ * @description 计算适合的 Buffer 长度
+ * @param {number} length 数据字节总大小
+ * @param {number} pageSize 缓冲区页大小
+ * @returns {number}
+ */
+function calcBufferLength(length, pageSize) {
+  if (length > pageSize) {
+    const pages = Math.ceil(length / pageSize);
+    return pages * pageSize;
+  } else {
+    return length;
+  }
+}
+
+exports.calcBufferLength = calcBufferLength;

package/cjs/utils.d.cts

@@ -0,0 +1,11 @@
+/**
+ * @module utils
+ */
+/**
+ * @function calcBufferLength
+ * @description 计算适合的 Buffer 长度
+ * @param {number} length 数据字节总大小
+ * @param {number} pageSize 缓冲区页大小
+ * @returns {number}
+ */
+export declare function calcBufferLength(length: number, pageSize: number): number;

package/esm/Binary.d.ts

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

package/esm/Binary.js

@@ -0,0 +1,23 @@
+/**
+ * @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
+ */
+
+/**
+ * @module Binary
+ */
+/**
+ * @type {string[]}
+ * @description 已获得的二进制映射表
+ */
+const mapping = [];
+// 生成映射表
+for (let code = 0; code < 256; code++) {
+  mapping[code] = String.fromCharCode(code);
+}
+
+export { mapping };

package/esm/Encoding/UTF8.d.ts

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

@@ -0,0 +1,30 @@
+/**
+ * @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
+ */
+
+/**
+ * @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);
+
+export { decode, encode };

package/esm/Encoding/Unicode.d.ts

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

@@ -0,0 +1,42 @@
+/**
+ * @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
+ */
+
+/**
+ * @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;
+}
+
+export { decode, encode };

package/esm/Encoding/index.d.ts

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

@@ -0,0 +1,62 @@
+/**
+ * @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
+ */
+
+import { encode as encode$2, decode as decode$2 } from './UTF8.js';
+import { encodingInvalid } from '../errors.js';
+import { encode as encode$1, decode as decode$1 } from './Unicode.js';
+
+/**
+ * @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 encode$2(input);
+    case 'UTF16':
+    case 'UTF-16':
+      return encode$1(input, Uint16Array);
+    case 'UTF32':
+    case 'UTF-32':
+      return encode$1(input, Uint32Array);
+    default:
+      throw new TypeError(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 decode$2(input);
+    case 'UTF16':
+    case 'UTF-16':
+      return decode$1(input, Uint16Array);
+    case 'UTF32':
+    case 'UTF-32':
+      return decode$1(input, Uint32Array);
+    default:
+      throw new TypeError(encodingInvalid(encoding));
+  }
+}
+
+export { decode, encode };

package/esm/enum.d.ts

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

@@ -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';

package/esm/errors.js

@@ -0,0 +1,28 @@
+/**
+ * @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
+ */
+
+/**
+ * @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';
+
+export { encodingInvalid, lengthInvalid, offsetInvalid, offsetOverflow, readOverflow, unknownEndianness };