trananhtung/structkit

# structkit [](https://www.npmjs.com/package/@billdaddy/structkit) [](LICENSE) ## 安装 ``` npm install @billdaddy/structkit ``` ## 快速开始 ``` import { pack, unpack, calcSize } from "@billdaddy/structkit"; // Pack a network protocol header (big-endian) const buf = pack("!IH", 0xdeadbeef, 42); // → Uint8Array [0xde, 0xad, 0xbe, 0xef, 0x00, 0x2a] // Unpack it back const { values } = unpack("!IH", buf); // → [0xdeadbeef, 42] calcSize("!IH"); // → 6 ``` ## 格式化字符串语法 ``` [byteorder] [count]formatchar ... ``` ### 字节序前缀 | 前缀 | 含义 | |---|---| | `<` | 小端序（默认） | | `>` | 大端序 | | `!` | 网络字节序（= 大端序） | | `=` | 原生（本实现：小端序） | | `@` | 原生对齐（本实现：小端序） | ### 格式字符 | 字符 | 类型 | 大小 | JS 类型 | |---|---|---|---| | `x` | 填充字节 | 1 | （无值） | | `?` | bool | 1 | boolean | | `b` | int8 | 1 | number | | `B` | uint8 | 1 | number | | `h` | int16 | 2 | number | | `H` | uint16 | 2 | number | | `i`/`l` | int32 | 4 | number | | `I`/`L` | uint32 | 4 | number | | `q` | int64 | 8 | **bigint** | | `Q` | uint64 | 8 | **bigint** | | `f` | float32 | 4 | number | | `d` | float64 | 8 | number | | `Ns` | N 字节字符串 | N | Uint8Array | | `Np` | pascal 字符串 | N | Uint8Array | 计数前缀会重复该类型：`3I` = 三个 uint32（12 字节）。 对于 `s`，计数字节长度：`4s` = 精确的 4 字节（零填充 / 截断）。 ## 示例 ``` import { pack, unpack, packInto, iterUnpack, Struct } from "@billdaddy/structkit"; // Repeat count: 3 uint32s const buf = pack("<3I", 100, 200, 300); unpack("<3I", buf).values; // [100, 200, 300] // Mixed types, big-endian pack(">bBhH", -1, 255, -256, 65535); // 6 bytes // Pad bytes (x) — consumed in pack, skipped in unpack pack(">BxB", 0xaa, 0xbb); // [0xaa, 0x00, 0xbb] unpack(">BxB", buf).values; // [0xaa, 0xbb] // Fixed-size byte string pack("4s", new Uint8Array([65, 66])); // [65, 66, 0, 0] pack("4s", "Hi"); // [72, 105, 0, 0] // int64 / uint64 — BigInt pack("H", buffer, 4).values; // skip first 4 bytes // Write into existing buffer const out = new Uint8Array(8); packInto(out, 2, ">H", 0xbeef); // write 2 bytes at offset 2 // Unpack multiple fixed-size records iterUnpack(">BI", buf); // → [[id, size], [id, size], ...] ``` ## Struct 类（可复用） 预解析格式化字符串以进行重复的 pack/unpack： ``` const header = new Struct("!4sHI"); // magic(4s) + version(H) + size(I) header.size; // 10 const buf = header.pack( new Uint8Array([0x89, 0x50, 0x4e, 0x47]), // PNG magic 1, // version 12345, // size ); const { values } = header.unpack(buf); // values[0] → Uint8Array [0x89, 0x50, 0x4e, 0x47] // values[1] → 1 // values[2] → 12345 ``` ## 网络协议示例 ``` import { Struct } from "@billdaddy/structkit"; // DNS header (RFC 1035) const DnsHeader = new Struct("!HHHHHH"); // id, flags, qdcount, ancount, nscount, arcount const buf = DnsHeader.pack( 0x1234, // id 0x0100, // flags: standard query 1, // 1 question 0, 0, 0, // no answers/ns/ar ); const { values: [id, flags, qdcount] } = DnsHeader.unpack(buf); ``` ## API ``` pack(fmt: string, ...values: unknown[]): Uint8Array unpack(fmt: string, buffer: Uint8Array, offset?: number): { values: unknown[]; bytesRead: number } packInto(buffer: Uint8Array, offset: number, fmt: string, ...values: unknown[]): number calcSize(fmt: string): number iterUnpack(fmt: string, buffer: Uint8Array): unknown[][] class Struct { constructor(format: string) readonly format: string readonly size: number pack(...values: unknown[]): Uint8Array unpack(buffer: Uint8Array, offset?: number): { values: unknown[]; bytesRead: number } packInto(buffer: Uint8Array, offset: number, ...values: unknown[]): number iterUnpack(buffer: Uint8Array): unknown[][] } class StructError extends Error {} ``` ## 为什么不用 binary-parser？ `binary-parser`（零依赖，2025）非常适合以声明式的方式**读取**复杂的二进制格式。`structkit` 则填补了**写入**方面的空白——目前没有 npm 包支持使用 `struct.pack` 风格的格式化字符串来打包二进制数据。 ## 许可证 MIT © [trananhtung](https://github.com/trananhtung)

标签：MITM代理, SOC Prime, TypeScript, 二进制数据, 内核驱动, 安全插件, 序列化, 开发工具, 数据可视化, 暗色界面, 网络协议, 自动化攻击, 零依赖