jsStruct

Описание и декодирование бинарных структур данных в JavaScript (браузер + Node.js). Аналог struct из C.

Возможности

• Регистрация типов — базовые целочисленные типы, float, строки, padding
• Структуры — именованные структуры из полей с автоматическим расчётом offset
• Вложенность — структура внутри структуры
• Массивы — count для повторяющихся полей
• Строки — фиксированной длины (string) и до NUL (cstring)
• Endianness — little-endian (по умолчанию) и big-endian
• Чтение/запись — AsUint8/16/32/64, AsInt8/16/32/64, AsFloat, AsDouble, AsString
• Нативный модуль (опционально) — ускорение через C++ (node-gyp)
• Без зависимостей в браузере — чистый JS, работает как ES-модуль
• TypeScript-типы — jsStruct.d.ts

Поддерживаемые форматы (тестовая страница)

Формат	Детекция	Что парсится
BMP	magic BM (0x4D42)	BMPFileHeader, BITMAPCOREHEADER, BITMAPINFOHEADER
JPEG	SOI 0xFFD8	SOF0 (precision, H, W, components), все маркеры
WSQ	SOI 0xFFA0 + DTT/DQT/DHT/SOF	SOF (black, white, H, W, mShift, rScale, encoder, software), DTT, DQT, DHT, все маркеры

Структура проекта

jsStruct/
├── index.js                    # HTTP-сервер (статические файлы, ESM)
├── package.json                # "type": "module"
├── rootHTML/
│   ├── index.html              # Тестовая страница (BMP / JPEG / WSQ)
│   ├── test.js                 # Парсеры BMP, JPEG, WSQ
│   └── jsModule/
│       ├── jsStruct.js         # Ядро (ES-модуль)
│       └── jsStruct.d.ts       # TypeScript-типы
├── native_module/
│   ├── building.gyp            # node-gyp конфиг (C++17)
│   └── src/testStruct.cpp      # Нативный C++ модуль
├── MIME-TYPE/
│   └── all.json                # База MIME-типов
├── test/
│   └── jsStruct.test.js        # Unit-тесты (node --test, 39 тестов)
├── .github/workflows/
│   └── ci.yml                  # CI: Node 20/22
└── LICENSE                     # GPL v3

Установка

npm install

Для нативного модуля (опционально):

npm run build:native

Быстрый старт

import { JSRegister, JSVariable } from './rootHTML/jsModule/jsStruct.js';

/* 1. Определить структуру */
JSRegister.struct('MyHeader', [
    { name: 'magic',   type: 'uint16' },
    { name: 'version', type: 'uint32' },
    { name: 'name',    type: 'string', count: 16 },
    { name: 'size',    type: 'uint64' }
]);

/* 2. Создать инстанс */
const header = new JSVariable('MyHeader');

/* 3. Записать данные (из файла, сети, ...) */
header.setMemory(arrayBuffer);

/* 4. Чтение полей */
console.log(header.magic.AsUint16);     /* number */
console.log(header.version.AsUint32);   /* number */
console.log(header.name.AsString);      /* string */
console.log(header.size.AsUint64);      /* bigint */

/* 5. Запись */
header.magic.AsUint16 = 0x4D42;
header.name.AsString = 'hello';

API

JSRegister

Метод	Описание
JSRegister.type(name, size)	Зарегистрировать базовый тип
JSRegister.struct(name, fields)	Зарегистрировать структуру
JSRegister.get(name)	Получить тип по имени
JSRegister.has(name)	Проверить наличие
JSRegister.clear()	Очистить реестр (встроенные типы восстанавливаются)
JSRegister.list()	Список всех имён

JSType

Базовый тип: имя + размер + (опционально) динамический размер.

JSStruct extends JSType

Структура из полей. Итерируема, предоставляет:

• fields — массив {name, type, count, offset, size}
• field(name) — info по имени
• totalSize — суммарный размер

JSValue

Обёртка над DataView. Геттеры/сеттеры:

AsUint8, AsInt8, AsUint16, AsInt16, AsUint32, AsInt32, AsUint64, AsInt64, AsFloat, AsDouble, AsString

JSVariable

Инстанс структуры:

• setMemory(buffer, byteOffset?) — загрузить данные
• getMemory() — получить ArrayBuffer
• toBytes() — получить Uint8Array
• Поля доступны как свойства: var.fieldName → JSValue

JSConfig

JSConfig.littleEndian = true;   /* порядок байтов */
JSConfig.native = true;         /* использовать нативный модуль */

Встроенные типы

Имя	Размер
int8, uint8	1
int16, uint16	2
int32, uint32	4
int64, uint64	8
float32	4
float64	8
string	count байт
cstring	до NUL
padding	count байт

Поля структуры

{ name: 'field', type: 'uint32' }                    // фиксированный тип
{ name: 'arr',   type: 'uint16', count: 10 }         // массив из 10
{ name: 'name',  type: 'string', count: 16 }         // строка 16 байт
{ name: 'path',  type: 'cstring' }                   // строка до NUL
{ name: 'pad',   type: 'padding', count: 4 }         // выравнивание
{ name: 'inner', type: 'InnerStruct' }               // вложенная структура

Тесты

npm test

39 unit-тестов (node --test), включая:

• Базовые типы и структуры
• Вложенность, массивы, строки
• Endianness (LE/BE)
• Чтение/запись всех типов
• JPEG SOF0 парсинг
• WSQ SOF парсинг

Сервер

npm start          # порт 8080
node index.js 9000 # порт 9000

Статический HTTP-сервер (ESM), MIME-типы из MIME-TYPE/all.json.

Нативный модуль

npm run build:native

C++17, node-addon-api (NAPI_DISABLE_CPP_EXCEPTIONS). Экспортирует: createStruct, readValue, writeValue, checksum (CRC32).

CI

GitHub Actions: Node 20 и 22, npm test + npm run lint.

Лицензия

GNU GPL v3