nv-facutil-ta-base

一个高效的 JavaScript 工具库，用于按块管理 ArrayBuffer 和类型化数组（TypedArray）操作。

简介

nv-facutil-ta-base 提供了一个 TaBase 类，用于将 ArrayBuffer 分割成等大小的块，并提供各种方法来操作这些块中的不同类型数据。这个工具在处理大型二进制数据、内存优化和数据结构管理方面非常有用。

特性

• 将 ArrayBuffer 分割成固定大小的块
• 支持所有标准 JavaScript 类型化数组：Uint8Array, Int8Array, Uint16Array, Int16Array, Uint32Array, Int32Array, Float32Array, BigUint64Array, BigInt64Array, Float64Array
• 提供安全的数据访问和写入方法
• 内置边界检查，防止数据溢出
• 高效的内存管理

安装

通过 npm 安装

npm install nv-facutil-ta-base

直接在项目中使用

const taBaseCreator = require('path/to/nv-facutil-ta-base');

基本用法

// 创建一个 ArrayBuffer
const bufferSize = 1024; // 1KB
const chunkSize = 64;    // 每个块 64 字节 (必须是 16 的倍数且大于 16)
const ab = new ArrayBuffer(bufferSize);

// 创建 TaBase 实例
const taBase = taBaseCreator(ab, chunkSize);

// 获取块数量
console.log(`块数量: ${taBase.chunk_cnt}`); // 输出: 块数量: 16

// 写入 Uint8 数据
taBase.set_u8a_unit_of_chunk(0, 0, 65); // 在第一个块的第一个位置写入 'A' (ASCII 65)

// 写入 Uint16 数据
taBase.set_u16a_unit_of_chunk(1, 0, 1000);

// 写入 Float32 数据
taBase.set_f32a_unit_of_chunk(2, 0, 3.14159);

// 写入一组字节
const bytes = new Uint8Array([72, 101, 108, 108, 111]); // "Hello" 的 ASCII 码
taBase.set_byts(3, 0, bytes);

API 参考

构造函数

/**
 * 创建一个 TaBase 实例
 * @param {ArrayBuffer} array_buf - 要分块管理的原始 ArrayBuffer
 * @param {number} chunksz - 每个块的字节大小，必须是16的倍数且大于16
 * @throws {Error} 当参数不满足要求时抛出错误
 */
const taBase = taBaseCreator(array_buf, chunksz);

属性

• chunksz: 每个块的字节大小
• chunk_cnt: 块的总数量（只读）

基本方法

获取块偏移量

/**
 * 获取指定块ID的字节偏移量
 * @param {number} id - 块的ID (从0开始)
 * @returns {number} 该块在 ArrayBuffer 中的字节偏移量
 */
taBase.get_offset(id);

获取单元索引

/**
 * 计算指定块中特定类型单元的索引
 * @param {number} id - 块的ID (从0开始)
 * @param {number} sz - 数据单元的字节大小 (如: 1表示8位, 2表示16位, 4表示32位, 8表示64位)
 * @param {number} relative_idx - 在当前块内的相对索引
 * @returns {number} 指定数据单元在对应类型化数组中的绝对索引
 */
taBase.get_unit_idx_of_chunk(id, sz, relative_idx);

获取单元偏移量

/**
 * 计算指定块中特定类型单元的字节偏移量
 * @param {number} id - 块的ID (从0开始)
 * @param {number} sz - 数据单元的字节大小
 * @param {number} relative_idx - 在当前块内的相对索引
 * @returns {number} 指定数据单元在 ArrayBuffer 中的字节偏移量
 */
taBase.get_unit_offset_of_chunk(id, sz, relative_idx);

写入字节数组

/**
 * 将一个 Uint8Array 写入指定块的指定偏移位置
 * @param {number} id - 块的ID
 * @param {number} relative_offset - 在当前块内的相对字节偏移量
 * @param {Uint8Array} u8a - 要写入的字节数组
 * @returns {boolean} 写入是否成功，如果超出块边界则返回false
 */
taBase.set_byts(id, relative_offset, u8a);

类型化数组写入方法

对于每种类型的数组，TaBase 提供了相应的写入方法：

• set_u8a_unit_of_chunk(id, relative_idx, val): 写入 8 位无符号整数
• set_i8a_unit_of_chunk(id, relative_idx, val): 写入 8 位有符号整数
• set_u16a_unit_of_chunk(id, relative_idx, val): 写入 16 位无符号整数
• set_i16a_unit_of_chunk(id, relative_idx, val): 写入 16 位有符号整数
• set_u32a_unit_of_chunk(id, relative_idx, val): 写入 32 位无符号整数
• set_i32a_unit_of_chunk(id, relative_idx, val): 写入 32 位有符号整数
• set_u64a_unit_of_chunk(id, relative_idx, val): 写入 64 位无符号整数
• set_i64a_unit_of_chunk(id, relative_idx, val): 写入 64 位有符号整数
• set_f32a_unit_of_chunk(id, relative_idx, val): 写入 32 位浮点数
• set_f64a_unit_of_chunk(id, relative_idx, val): 写入 64 位浮点数

示例

创建一个简单的结构化数据存储

// 创建一个可以存储 100 个记录的 ArrayBuffer，每个记录 64 字节
const recordCount = 100;
const recordSize = 64;
const ab = new ArrayBuffer(recordCount * recordSize);
const records = taBaseCreator(ab, recordSize);

// 定义记录结构
// 假设每个记录包含：id (u32), name (16字节), age (u8), salary (f32)

// 写入第一条记录
const recordId = 0;
records.set_u32a_unit_of_chunk(recordId, 0, 1001);       // id: 1001
records.set_u8a_unit_of_chunk(recordId, 8, 30);          // age: 30
records.set_f32a_unit_of_chunk(recordId, 2, 5000.50);    // salary: 5000.50

// 写入名字 (假设用 ASCII 编码)
const nameBytes = new Uint8Array([74, 111, 104, 110, 32, 68, 111, 101]); // "John Doe"
records.set_byts(recordId, 4, nameBytes);

// 写入第二条记录
records.set_u32a_unit_of_chunk(1, 0, 1002);              // id: 1002
records.set_u8a_unit_of_chunk(1, 8, 25);                 // age: 25
records.set_f32a_unit_of_chunk(1, 2, 4500.75);           // salary: 4500.75

// 写入名字
const nameBytes2 = new Uint8Array([74, 97, 110, 101, 32, 83, 109, 105, 116, 104]); // "Jane Smith"
records.set_byts(1, 4, nameBytes2);

实现简单的内存数据库索引

// 创建一个索引结构，每个索引项 32 字节
const indexCount = 1000;
const indexSize = 32;
const ab = new ArrayBuffer(indexCount * indexSize);
const indexes = taBaseCreator(ab, indexSize);

// 索引结构：key (u32), pointer (u32), timestamp (f64)

// 添加索引项
function addIndex(id, key, pointer, timestamp) {
  indexes.set_u32a_unit_of_chunk(id, 0, key);        // key
  indexes.set_u32a_unit_of_chunk(id, 1, pointer);    // pointer
  indexes.set_f64a_unit_of_chunk(id, 1, timestamp);  // timestamp
}

// 使用示例
addIndex(0, 12345, 500000, Date.now());
addIndex(1, 67890, 600000, Date.now());

注意事项

• 块大小 (chunksz) 必须是 16 的倍数且大于 16。
• ArrayBuffer 的大小必须是块大小的整数倍。
• 当尝试写入超出块边界的数据时，set_byts 方法会返回 false 并且不会写入任何数据。