@1337exp/2pack 0.0.0-stage → 2.0.0-dev.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 2.0.0-dev.0
+
+A rewrite from scratch; not compatible with 1.x.
+
+- Schema as TypeScript values (`define({ hp: i16 })`), types inferred from the schema.
+- Byte format specified in `docs/spec.md`, with test vectors. Fields are written in schema order, little-endian, varint lengths.
+- Three ways to pack with explicit ownership: `pack` (fresh copy), `packInto` (your buffer), `packShared` (view of the codec's buffer).
+- Declared maximum for every string, byte array and list; values over it are errors, never truncated. Integers are checked, not wrapped.
+- Decoding is bounds-checked and throws only `PackError`, with a `code` and a `path`.
+- New types: `bool`, `varuint`, `varint`, `optional`, `array`, `enumOf`, `quant`, nested `define`.
+- Schema evolution by appending: `added(type, default)` fields at the end of a top-level record, and `define(shape, { extensible: true })` so that a first version already ignores what a later one appends. Strict stays the default: only an explicit `extensible: true` accepts bytes after the last known field, `added` alone does not. Zero bytes on the wire, no measurable speed cost, rules in `docs/spec.md`.
+- Zero dependencies, ESM only, no code generation, no build step beyond `tsc`.
+- Removed: runtime string schemas, the `offset` setter, `json<N>`, the browser Buffer polyfill, the UMD bundle.
+
+Fixed before the first release, after an independent review of the first commit (each has a regression test in `tests/regressions.test.ts`):
+
+- `packInto` of a short string whose declared maximum was 128 or more wrote 1 to 4 stray bytes after the packet, and refused a buffer of exactly the packet's size. The body is now written where it ends up.
+- A resizable, growable or detached buffer reused through the same `Uint8Array` object read or wrote through a stale view (wrong `overflow`, raw `RangeError` / `TypeError`). The view is rebuilt when the length or offset changes, and an unusable buffer is a `PackError`.
+- `quant(-Number.MAX_VALUE, Number.MAX_VALUE, bits)` encoded everything as 0 and decoded `NaN`: the span overflowed to `Infinity`. Now refused when the schema is built.
+- An array was accepted as a record (`define({ length: u8 }).pack([1, 2, 3, 4])`).
+- `define` made optional fields required in the TypeScript type; they can now be left out.
+- A value too big to allocate a scratch buffer for threw a raw `RangeError`; it is a `PackError` now.
+
+`npm run browser` runs 95 checks (spec vectors, ownership, bounds, hostile input, resizable and detached buffers) in a real browser; passed in Chromium 152.
+
+`npm run mutate` breaks the code in 35 deliberate ways, one at a time, and checks that the tests notice every one.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1337exp
+
+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

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# 2pack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** · [Русский](README.ru.md)
+
+A tiny schema-first binary codec for Node and browsers. You describe a packet once, in TypeScript; the type is inferred, the bytes are small, and decoding hostile input can only ever throw one kind of error. No dependencies, no code generation, you own the buffers.
+
+> Version 2 is a rewrite and **not compatible with 1.x**: the field order, the size prefixes and the whole API changed.
+
+## Stack
+
+TypeScript 6, ESM only, zero runtime dependencies, Node 18+ and any modern browser. Tests with vitest.
+
+## Quick start
+
+```ts
+import { array, define, enumOf, i16, quant, str, u8, varuint, type Infer } from '@1337exp/2pack';
+
+const Packet = define({
+    kind: enumOf(['join', 'move', 'chat']),
+    name: str(16), // at most 16 UTF-8 bytes; longer is an error, never truncated
+    hp: i16,
+    pos: define({ x: quant(-500, 500, 16), y: quant(-500, 500, 16) }), // 2 bytes each, error under 0.008
+    items: array(define({ id: varuint, count: u8 }), 8),
+});
+
+type Packet = Infer<typeof Packet>; // { kind: 'join' | 'move' | 'chat'; name: string; hp: number; ... }
+
+const bytes = Packet.pack({ kind: 'move', name: 'D', hp: -13, pos: { x: 12.5, y: -3 }, items: [{ id: 7, count: 2 }] });
+const value = Packet.unpack(bytes); // typed, validated, or a PackError
+```
+
+Several packets in one buffer (a header, then a payload), with no allocation:
+
+```ts
+const Header = define({ type: u8, version: u8 });
+const Hello = define({ name: str(16), hp: i16 });
+const buf = new Uint8Array(Header.max + Hello.max);
+
+let n = Header.packInto(buf, { type: 3, version: 1 });
+n += Hello.packInto(buf, { name: 'D', hp: 100 }, n);
+
+const [header, at] = Header.unpackAt(buf, 0, n);
+const payload = Hello.unpack(buf, at, n);
+```
+
+## Types
+
+| | |
+|---|---|
+| `bool` `u8` `i8` `u16` `i16` `u32` `i32` `f32` `f64` | fixed-size, little-endian |
+| `u64` `i64` | 8 bytes, `bigint` |
+| `varuint` `varint` | 1 to 5 bytes, small numbers cost one byte |
+| `str(maxBytes)` `bytes(maxBytes)` | length-prefixed, the maximum is mandatory |
+| `array(item, maxCount)` `optional(item)` `enumOf([...])` | |
+| `quant(min, max, bits)` | a number in a known range stored in 8, 16 or 32 bits |
+| `define({...})` | a record, fields in declaration order, names are not sent |
+| `added(item, default)` | a field added in a newer version, last in its record, see [Evolving a packet](#evolving-a-packet) |
+
+Every variable-size type has a declared maximum, so every codec has a finite `min` and `max` size: `new Uint8Array(codec.max)` always fits.
+
+The byte-level format is in [docs/spec.md](docs/spec.md), with test vectors in `tests/vectors.ts`.
+
+## Evolving a packet
+
+Packets are strict, and **strict is the default**: no names or tags on the wire, a reader needs the schema that wrote the packet, and any byte beyond the last field is an error. Flexibility is opt-in, per message, with `{ extensible: true }`. One kind of change is supported, and it costs nothing on the wire or in speed: **appending fields at the end**.
+
+```ts
+// version 1: declared extensible from the start, so it already ignores fields a later version appends
+const Player = define({ id: u32, name: str(16) }, { extensible: true });
+
+// version 2: the new field goes last, wrapped in added(); an older packet decodes with the default
+const Player = define({ id: u32, name: str(16), shield: added(u16, 0) }, { extensible: true });
+```
+
+New server, old client and old server, new client both work: a new reader fills what an old packet lacks, an old reader skips what a new packet adds. The rules and what it cannot do (removing or reordering fields, nesting) are in [docs/spec.md](docs/spec.md#evolution). Two things to know: it relies on the transport telling you where the packet ends (a WebSocket message does), and an extensible record no longer reports extra bytes as an error (that is the price of opting in).
+
+## You own the buffer
+
+Three ways to pack, and a page explaining why:
+
+| | allocation | the bytes |
+|---|---|---|
+| `pack(value)` | one per packet | yours forever (default, always safe) |
+| `packInto(buf, value, offset?)` | none | in **your** buffer |
+| `packShared(value)` | none | a view, overwritten by the next call |
+
+Handing a `packShared` view to `socket.write()` is a real bug under backpressure: [Who owns the bytes](docs/buffer-ownership.md) shows it happening and explains it. `npm run backpressure` reproduces it on your machine.
+
+## Safe by construction
+
+- Nothing wraps and nothing is truncated: `300` into `u8`, `1.5` into `u16`, `NaN` into `i32` and a string over its limit are errors that say where (`players[3].hp`).
+- Decoding never reads outside `[offset, end)` and checks every length against both its declared maximum and the bytes that remain. A count of a billion items in a ten-byte packet is rejected before anything is allocated.
+- Hostile or corrupt bytes throw `PackError` and nothing else: checked by tests with truncation of every packet at every length and 40 000 random corruptions.
+- Results are plain objects that own their data. `packInto` writes only the packet's bytes.
+- The same checks run in a real browser: `npm run browser` serves a page that runs the spec vectors, the fuzzing and the resizable-buffer cases against the library and turns the tab title into PASS or FAIL (tried in Chromium; no dependencies).
+
+## How much to trust it
+
+A serializer sits on the network edge, so it should be tested like it. What this one has been through:
+
+- **338 tests**, and the byte format is pinned by **53 hand-computed vectors** from the spec, each checked packing, unpacking, into an exactly sized buffer and with the surroundings untouched.
+- **Seeded, reproducible fuzzing.** Thousands of random packets round-trip; every packet is truncated at every length; 40 000 random single-byte corruptions and 20 000 random buffers are fed to the decoders. The rule being tested: decoding hostile bytes throws `PackError` and nothing else, and never allocates for a length the input cannot back.
+- **Mutation check** (`npm run mutate`): the code is broken in 35 deliberate ways, one at a time (drop a bounds check, flip a byte order, wrap instead of reject, ...), and the tests must notice every one. They do. The first run let 2 of 19 through, which exposed two weak tests, now fixed.
+- **Independent adversarial review** by another AI model (Grok), which read the spec and wrote its own differential fuzzers against the library. It found 6 bugs, one of them serious (`packInto` wrote bytes after the end of the packet) and missed by our own tests. All fixed, each pinned by a regression test (`tests/regressions.test.ts`).
+- **A real browser**: `npm run browser` runs 95 checks in the page (Chromium 152).
+
+What it has **not** had: a human security audit, production traffic, Firefox or Safari, or a big-endian machine. Version 2 is a development build, so pin the exact version until it has been out for a while.
+
+## Speed and size
+
+One machine (Node 22, Windows), small objects, median of 5 runs. `npm run bench` reproduces it. Compared on the safe `pack`, which copies.
+
+| | size | encode | decode |
+|---|---|---|---|
+| **2pack**, 24-byte game record | **24 B** | **108 ns** | **144 ns** |
+| msgpackr | 57 B | 217 ns | 195 ns |
+| cbor-x | 58 B | 205 ns | 334 ns |
+| JSON (as bytes) | 70 B | 442 ns | 763 ns |
+| **2pack**, snapshot of 20 units | **144 B** | **1246 ns** | **1265 ns** |
+| msgpackr | 608 B | 2164 ns | 3607 ns |
+| cbor-x | 634 B | 2554 ns | 3740 ns |
+| JSON (as bytes) | 792 B | 3849 ns | 4767 ns |
+
+The size win is the structural one: with a schema on both sides, names and type tags are not sent. If you cannot share a schema, use msgpackr or cbor-x; they are good.
+
+## Not yet
+
+- **Removing or reordering fields.** Only appending is supported; anything else goes through a version in a small header codec (see the spec).
+- **A second implementation.** The format is specified byte for byte so another language can implement it, but only the TypeScript one exists.
+- **A CommonJS build.** ESM only; Node 22 can `require()` it.
+
+## Commands
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run bench
+npm run mutate
+npm run backpressure
+npm run browser
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+## Us
+
+Homepage: [666.io](https://666.io). If you want to help, suggest an idea or just talk, come by.

package/README.ru.md

@@ -0,0 +1,150 @@
+# 2pack
+
+[English](README.md) · **Русский**
+
+Крошечный бинарный кодек со схемой для Node и браузеров. Пакет описывается один раз на TypeScript: тип выводится сам, байтов мало, а при разборе враждебных данных можно получить только один вид ошибки. Без зависимостей, без кодогенерации, буферами владеете вы.
+
+> Версия 2 — переписанная с нуля и **несовместима с 1.x**: порядок полей, префиксы размеров и весь API изменились.
+
+## Стек
+
+TypeScript 6, только ESM, ноль зависимостей в рантайме, Node 18+ и любой современный браузер. Тесты на vitest.
+
+## Быстрый старт
+
+```ts
+import { array, define, enumOf, i16, quant, str, u8, varuint, type Infer } from '@1337exp/2pack';
+
+const Packet = define({
+    kind: enumOf(['join', 'move', 'chat']),
+    name: str(16), // не больше 16 байт UTF-8; длиннее — ошибка, без обрезки
+    hp: i16,
+    pos: define({ x: quant(-500, 500, 16), y: quant(-500, 500, 16) }), // по 2 байта, ошибка меньше 0,008
+    items: array(define({ id: varuint, count: u8 }), 8),
+});
+
+type Packet = Infer<typeof Packet>; // { kind: 'join' | 'move' | 'chat'; name: string; hp: number; ... }
+
+const bytes = Packet.pack({ kind: 'move', name: 'D', hp: -13, pos: { x: 12.5, y: -3 }, items: [{ id: 7, count: 2 }] });
+const value = Packet.unpack(bytes); // с типом и проверкой, либо PackError
+```
+
+Несколько пакетов в одном буфере (заголовок, потом данные), без аллокаций:
+
+```ts
+const Header = define({ type: u8, version: u8 });
+const Hello = define({ name: str(16), hp: i16 });
+const buf = new Uint8Array(Header.max + Hello.max);
+
+let n = Header.packInto(buf, { type: 3, version: 1 });
+n += Hello.packInto(buf, { name: 'D', hp: 100 }, n);
+
+const [header, at] = Header.unpackAt(buf, 0, n);
+const payload = Hello.unpack(buf, at, n);
+```
+
+## Типы
+
+| | |
+|---|---|
+| `bool` `u8` `i8` `u16` `i16` `u32` `i32` `f32` `f64` | фиксированный размер, little-endian |
+| `u64` `i64` | 8 байт, `bigint` |
+| `varuint` `varint` | от 1 до 5 байт, малые числа занимают один байт |
+| `str(maxBytes)` `bytes(maxBytes)` | с префиксом длины, максимум обязателен |
+| `array(item, maxCount)` `optional(item)` `enumOf([...])` | |
+| `quant(min, max, bits)` | число из известного диапазона в 8, 16 или 32 битах |
+| `define({...})` | запись, поля в порядке объявления, имена не передаются |
+| `added(item, default)` | поле, добавленное в новой версии, последним в записи, см. [Как менять пакет](#как-менять-пакет) |
+
+У каждого типа переменного размера объявлен максимум, поэтому у любого кодека конечные `min` и `max`: `new Uint8Array(codec.max)` всегда вмещает значение.
+
+Формат на уровне байтов описан в [docs/spec.md](docs/spec.md), эталонные байты в `tests/vectors.ts`.
+
+## Как менять пакет
+
+Пакеты строгие, и **строгий режим по умолчанию**: на проводе нет ни имён, ни тегов, читателю нужна схема, которой записан пакет, а любой байт после последнего поля — ошибка. Гибкость включается явно, для каждого сообщения, через `{ extensible: true }`. Поддерживается один вид изменений, и он ничего не стоит ни в байтах, ни в скорости: **дописывание полей в конец**.
+
+```ts
+// версия 1: сразу объявлена расширяемой, поэтому уже игнорирует поля, которые допишет следующая версия
+const Player = define({ id: u32, name: str(16) }, { extensible: true });
+
+// версия 2: новое поле последним, в обёртке added(); старый пакет читается со значением по умолчанию
+const Player = define({ id: u32, name: str(16), shield: added(u16, 0) }, { extensible: true });
+```
+
+Работают оба направления: новый сервер со старым клиентом и старый сервер с новым клиентом. Новый читатель подставляет то, чего нет в старом пакете, старый читатель пропускает то, что дописал новый. Правила и то, чего это не умеет (удалять и переставлять поля, вкладывать), описаны в [docs/spec.md](docs/spec.md#evolution). Две вещи, которые надо знать: нужна граница пакета от транспорта (у сообщения WebSocket она есть), и расширяемая запись больше не считает лишние байты ошибкой (это цена включения).
+
+## Буфер ваш
+
+Три способа упаковки и страница, которая объясняет почему:
+
+| | аллокации | байты |
+|---|---|---|
+| `pack(value)` | одна на пакет | ваши навсегда (по умолчанию, всегда безопасно) |
+| `packInto(buf, value, offset?)` | нет | в **вашем** буфере |
+| `packShared(value)` | нет | окно, следующий вызов его перезапишет |
+
+Отдать окно от `packShared` в `socket.write()` — настоящая ошибка при backpressure: [Чьи это байты](docs/buffer-ownership.ru.md) показывает, как она случается, и объясняет. `npm run backpressure` воспроизводит её у вас на машине.
+
+## Безопасно по построению
+
+- Ничего не заворачивается и не обрезается: `300` в `u8`, `1.5` в `u16`, `NaN` в `i32` и строка длиннее лимита — ошибки с указанием места (`players[3].hp`).
+- Разбор никогда не читает за пределами `[offset, end)` и сверяет каждую длину и с объявленным максимумом, и с оставшимися байтами. Миллиард элементов в десятибайтовом пакете отклоняется до всякого выделения памяти.
+- Враждебные и битые байты дают `PackError` и ничего другого: проверено тестами с обрезанием каждого пакета на каждую длину и 40 000 случайных порч.
+- Результаты — обычные объекты, которые владеют своими данными. `packInto` пишет только байты пакета.
+- Те же проверки идут в настоящем браузере: `npm run browser` поднимает страницу, которая прогоняет на библиотеке эталонные векторы, фаззинг и случаи с изменяемыми буферами, а заголовок вкладки становится PASS или FAIL (проверено в Chromium; без зависимостей).
+
+## Насколько ей можно доверять
+
+Сериализатор стоит на границе с сетью, поэтому и тестировать его надо соответственно. Что прошла эта библиотека:
+
+- **338 теста**, а формат на уровне байтов закреплён **53 эталонными векторами** из спецификации, посчитанными вручную: каждый проверен на упаковку, распаковку, запись в буфер точного размера и на то, что вокруг ничего не тронуто.
+- **Воспроизводимый фаззинг** с зерном. Тысячи случайных пакетов проходят круг упаковки и распаковки; каждый пакет обрезается на каждую длину; в декодеры подаётся 40 000 случайных порч одного байта и 20 000 случайных буферов. Проверяемое правило: разбор враждебных байтов бросает `PackError` и ничего другого и не выделяет память под длину, которую вход не может подтвердить.
+- **Проверка мутациями** (`npm run mutate`): код ломается 35 намеренными способами по одному (убрать проверку границ, перевернуть порядок байт, заворачивать вместо отказа и т. д.), и тесты обязаны заметить каждый. Замечают. С первого раза пропустили 2 из 19, это выявило два слабых теста, теперь исправлены.
+- **Независимое состязательное ревью** другой модели (Grok): она прочитала спецификацию и написала собственные дифференциальные фаззеры против библиотеки. Нашла 6 ошибок, одна серьёзная (`packInto` писал байты после конца пакета), наши тесты её пропустили. Все исправлены, на каждую есть регрессионный тест (`tests/regressions.test.ts`).
+- **Настоящий браузер**: `npm run browser` прогоняет 95 проверок на странице (Chromium 152).
+
+Чего у неё **не было**: аудита безопасности людьми, боевого трафика, Firefox и Safari, big-endian машины. Версия 2 — сборка для разработки, поэтому фиксируйте точную версию, пока она не отлежится.
+
+## Скорость и размер
+
+Одна машина (Node 22, Windows), мелкие объекты, медиана из 5 прогонов. Воспроизводится `npm run bench`. Сравнение по безопасному `pack`, который копирует.
+
+| | размер | кодирование | разбор |
+|---|---|---|---|
+| **2pack**, запись 24 байта | **24 Б** | **108 нс** | **144 нс** |
+| msgpackr | 57 Б | 217 нс | 195 нс |
+| cbor-x | 58 Б | 205 нс | 334 нс |
+| JSON (в байтах) | 70 Б | 442 нс | 763 нс |
+| **2pack**, снимок из 20 юнитов | **144 Б** | **1246 нс** | **1265 нс** |
+| msgpackr | 608 Б | 2164 нс | 3607 нс |
+| cbor-x | 634 Б | 2554 нс | 3740 нс |
+| JSON (в байтах) | 792 Б | 3849 нс | 4767 нс |
+
+Выигрыш в размере структурный: когда схема есть у обеих сторон, имена и теги типов не передаются. Если схемой поделиться нельзя, берите msgpackr или cbor-x: они хороши.
+
+## Пока нет
+
+- **Удаления и перестановки полей.** Поддерживается только дописывание; остальное идёт через версию в небольшом кодеке-заголовке (см. спецификацию).
+- **Второй реализации.** Формат описан по байтам, чтобы на другом языке можно было реализовать, но существует только TypeScript.
+- **Сборки CommonJS.** Только ESM; Node 22 умеет `require()` для него.
+
+## Команды
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run bench
+npm run mutate
+npm run backpressure
+npm run browser
+```
+
+## Лицензия
+
+MIT, см. [LICENSE](LICENSE).
+
+## Мы
+
+Домашняя страница: [666.io](https://666.io). Хочешь помочь, предложить идею или просто поговорить — заходи.

package/dist/codec.d.ts

@@ -0,0 +1,100 @@
+/**
+ * A codec for values of type `T`: one object that knows how to write `T` to bytes and read it back.
+ * Every codec has a finite `min` and `max` size in bytes, so `new Uint8Array(codec.max)` always fits any value.
+ *
+ * Кодек значений типа `T`: умеет писать `T` в байты и читать обратно. У любого кодека конечные `min` и `max`
+ * (в байтах), поэтому `new Uint8Array(codec.max)` вмещает любое значение.
+ */
+export interface Codec<T> {
+    /** Smallest possible encoded size in bytes. / Минимальный размер в байтах. */
+    readonly min: number;
+    /** Largest possible encoded size in bytes. / Максимальный размер в байтах. */
+    readonly max: number;
+    /**
+     * Encode into a **new** array that you own. Safe to keep, queue or send later. One allocation.
+     * Упаковать в **новый** массив, он ваш: его можно хранить, ставить в очередь, отправлять позже.
+     */
+    pack(data: T): Uint8Array;
+    /**
+     * Encode into **your** buffer starting at `offset`; returns the number of bytes written.
+     * No allocation, and nothing else touches your bytes. Throws `overflow` if the buffer is too small.
+     * Упаковать в **ваш** буфер с `offset`; возвращает число записанных байт. Без аллокаций, чужого
+     * кода в ваших байтах нет. Если буфера мало, `overflow`.
+     */
+    packInto(buf: Uint8Array, data: T, offset?: number): number;
+    /**
+     * Encode into this codec's internal scratch buffer and return a **view** of it. Zero data allocation, but the
+     * bytes are overwritten by the next `pack` or `packShared` on this codec: copy them or finish sending
+     * before then. Do NOT hand the view to `socket.write()` / `ws.send()` and encode again in the same tick:
+     * see docs/buffer-ownership.md.
+     * Упаковать во внутренний буфер кодека и вернуть **окно** на него. Данные не копируются, но следующий
+     * `pack*` этого кодека перезапишет их. Нельзя отдавать окно в `socket.write()` / `ws.send()` и упаковывать
+     * дальше в том же такте: см. docs/buffer-ownership.md.
+     */
+    packShared(data: T): Uint8Array;
+    /**
+     * Decode one value from `buf[offset, end)`. The value must fill that range exactly, otherwise `invalid`
+     * (trailing bytes) or `truncated`. Throws only `PackError`.
+     * Прочитать одно значение из `buf[offset, end)`. Оно должно занять диапазон ровно, иначе `invalid`
+     * (лишние байты) или `truncated`. Бросает только `PackError`.
+     */
+    unpack(buf: Uint8Array | ArrayBuffer, offset?: number, end?: number): T;
+    /**
+     * Like `unpack`, but extra bytes after the value are allowed; returns the value and the offset after it.
+     * Use it to read several values from one buffer.
+     * Как `unpack`, но лишние байты после значения допустимы; возвращает значение и смещение за ним.
+     */
+    unpackAt(buf: Uint8Array | ArrayBuffer, offset?: number, end?: number): [value: T, end: number];
+}
+/** The TypeScript type a codec encodes. / TypeScript-тип, который кодирует кодек. */
+export type Infer<C> = C extends Codec<infer T> ? T : never;
+/** Field names whose value may be `undefined` (they come from `optional(...)`). */
+type OptionalKeys<S extends Record<string, Codec<any>>> = {
+    [K in keyof S]: undefined extends Infer<S[K]> ? K : never;
+}[keyof S];
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * The value type of `define(shape)`: fields from `optional(...)` may be left out.
+ * Тип значения для `define(shape)`: поля из `optional(...)` можно не указывать.
+ */
+export type Value<S extends Record<string, Codec<any>>> = Simplify<{
+    [K in Exclude<keyof S, OptionalKeys<S>>]: Infer<S[K]>;
+} & {
+    [K in OptionalKeys<S>]?: Infer<S[K]>;
+}>;
+/** @internal Cursor over a buffer being written. */
+export declare class Writer {
+    u8: Uint8Array;
+    dv: DataView;
+    pos: number;
+    /** What `dv` was built for; see `bind`. */
+    boundLen: number;
+    boundOff: number;
+}
+/** @internal Cursor over a buffer being read; `end` is exclusive. */
+export declare class Reader {
+    u8: Uint8Array;
+    dv: DataView;
+    pos: number;
+    end: number;
+    boundLen: number;
+    boundOff: number;
+}
+/** @internal A codec plus the two functions that composite codecs call. */
+export interface Impl<T> extends Codec<T> {
+    write(w: Writer, v: T): void;
+    read(r: Reader): T;
+    /**
+     * The record depends on where its range ends (it has `added` fields or is `extensible`), so it must be the
+     * top-level codec: something placed after it could never be found.
+     */
+    readonly open: boolean;
+    /** Set by `added(...)`: the field may be missing from older packets and then takes `fallback`. */
+    readonly isAdded?: boolean;
+    readonly fallback?: unknown;
+}
+/** @internal */
+export declare function make<T>(min: number, max: number, write: (w: Writer, v: T) => void, read: (r: Reader) => T, open?: boolean, lenient?: boolean): Impl<T>;
+export {};

package/dist/codec.js

@@ -0,0 +1,168 @@
+import { fail, PackError } from './errors.js';
+// ---------------------------------------------------------------------------------------------------------------
+// Internals / Внутреннее устройство
+// ---------------------------------------------------------------------------------------------------------------
+/** @internal Cursor over a buffer being written. */
+export class Writer {
+    u8 = new Uint8Array(0);
+    dv = new DataView(this.u8.buffer);
+    pos = 0;
+    /** What `dv` was built for; see `bind`. */
+    boundLen = -1;
+    boundOff = -1;
+}
+/** @internal Cursor over a buffer being read; `end` is exclusive. */
+export class Reader {
+    u8 = new Uint8Array(0);
+    dv = new DataView(this.u8.buffer);
+    pos = 0;
+    end = 0;
+    boundLen = -1;
+    boundOff = -1;
+}
+/**
+ * Point a cursor at `buf`. The DataView is rebuilt unless it was built for this very array with the same length
+ * and offset: a resizable or growable buffer changes length under the same Uint8Array object, and a transferred
+ * (detached) one must not be used through a stale view. A zero-length array is always rebuilt, because a
+ * detached buffer also reports length 0.
+ * Привязать курсор к `buf`. DataView пересоздаётся, если это не тот же массив с той же длиной и смещением
+ * (изменяемый буфер меняет длину, отвязанный нельзя использовать через старое окно).
+ */
+function bind(c, buf) {
+    const len = buf.byteLength;
+    const off = buf.byteOffset;
+    if (c.u8 === buf && c.boundLen === len && c.boundOff === off && len !== 0)
+        return;
+    let dv;
+    try {
+        dv = new DataView(buf.buffer, off, len);
+    }
+    catch {
+        return fail('usage', 'the buffer is detached or cannot be used (was it transferred or resized?)');
+    }
+    c.u8 = buf;
+    c.dv = dv;
+    c.boundLen = len;
+    c.boundOff = off;
+}
+// One cursor per direction, reused by every call. JS runs one thread of user code at a time and neither
+// direction calls back into user code except through property getters on the data being packed, which the
+// `writing` flag guards. Rebinding the DataView only when the buffer changes keeps repeated calls on the
+// same buffer allocation-free.
+// Один курсор на направление, общий для всех вызовов. DataView пересоздаётся, только когда сменился буфер.
+const writer = new Writer();
+const reader = new Reader();
+let writing = false;
+/** Scratch buffers above this size are not kept between calls. / Буферы больше этого размера не хранятся. */
+const SCRATCH_KEEP = 1 << 20;
+/** @internal */
+export function make(min, max, write, read, open = false, lenient = false) {
+    let scratch = null;
+    let lastLen = 0;
+    function packIntoImpl(buf, data, offset) {
+        if (!(buf instanceof Uint8Array))
+            fail('type', 'packInto: buf must be a Uint8Array');
+        if (!Number.isInteger(offset) || offset < 0 || offset > buf.length) {
+            fail('usage', `packInto: offset ${offset} is outside the buffer (length ${buf.length})`);
+        }
+        if (writing)
+            fail('usage', 'pack called while another pack is running (from a getter?)');
+        const w = writer;
+        bind(w, buf);
+        w.pos = offset;
+        writing = true;
+        try {
+            write(w, data);
+        }
+        catch (e) {
+            // A DataView store past the end throws RangeError; that is exactly "buffer too small".
+            if (e instanceof RangeError && !(e instanceof PackError)) {
+                throw new PackError('overflow', `buffer too small: ${buf.length - offset} bytes available after offset ${offset}`);
+            }
+            throw e;
+        }
+        finally {
+            writing = false;
+        }
+        return w.pos - offset;
+    }
+    /** Encode into the scratch buffer (growing it if `max` is large); result length is left in `lastLen`. */
+    function encodeScratch(data) {
+        let size = scratch ? scratch.length : Math.min(max, SCRATCH_KEEP);
+        for (;;) {
+            let buf;
+            if (scratch && scratch.length >= size) {
+                buf = scratch;
+            }
+            else {
+                try {
+                    buf = new Uint8Array(size);
+                }
+                catch {
+                    // Growing x4 can ask for more than the process can allocate for a value that would have fit.
+                    throw new PackError('range', `this value needs a buffer of up to ${size} bytes, which cannot be allocated`);
+                }
+            }
+            try {
+                lastLen = packIntoImpl(buf, data, 0);
+            }
+            catch (e) {
+                if (e instanceof PackError && e.code === 'overflow' && size < max) {
+                    size = Math.min(max, size * 4);
+                    continue;
+                }
+                throw e;
+            }
+            if (buf.length <= SCRATCH_KEEP)
+                scratch = buf;
+            return buf;
+        }
+    }
+    function unpackAtImpl(input, offset, end) {
+        const buf = input instanceof ArrayBuffer ? new Uint8Array(input) : input;
+        if (!(buf instanceof Uint8Array))
+            fail('type', 'unpack: buf must be a Uint8Array or an ArrayBuffer');
+        const stop = end === undefined ? buf.length : end;
+        if (!Number.isInteger(offset) || !Number.isInteger(stop) || offset < 0 || stop < offset || stop > buf.length) {
+            fail('usage', `unpack: range [${offset}, ${stop}) is outside the buffer (length ${buf.length})`);
+        }
+        const r = reader;
+        bind(r, buf);
+        r.pos = offset;
+        r.end = stop;
+        return stop;
+    }
+    const codec = {
+        min,
+        max,
+        open,
+        write,
+        read,
+        pack(data) {
+            const buf = encodeScratch(data);
+            return buf.slice(0, lastLen);
+        },
+        packInto(buf, data, offset = 0) {
+            return packIntoImpl(buf, data, offset);
+        },
+        packShared(data) {
+            const buf = encodeScratch(data);
+            return buf.subarray(0, lastLen);
+        },
+        unpack(input, offset = 0, end) {
+            const stop = unpackAtImpl(input, offset, end);
+            const value = read(reader);
+            // Strict by default: every byte must belong to the value. Only a record explicitly declared
+            // `extensible` accepts bytes after its last known field (fields a newer writer appended).
+            if (!lenient && reader.pos !== stop)
+                fail('invalid', `${stop - reader.pos} trailing byte(s) after the value`);
+            return value;
+        },
+        unpackAt(input, offset = 0, end) {
+            const stop = unpackAtImpl(input, offset, end);
+            const value = read(reader);
+            return [value, lenient ? stop : reader.pos];
+        },
+    };
+    return codec;
+}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Why a pack or unpack call failed. See docs/spec.md for the full table.
+ * Почему упаковка или распаковка не удалась. Полная таблица в docs/spec.md.
+ */
+export type PackErrorCode = 'type' | 'range' | 'overflow' | 'truncated' | 'invalid' | 'usage';
+/**
+ * The only error type 2pack throws for bad data. `code` says what went wrong, `path` where
+ * (for example `players[3].hp`). Decoding hostile bytes throws nothing else.
+ * Единственный тип ошибки 2pack для плохих данных. `code` говорит, что не так, `path` где
+ * (например `players[3].hp`). Разбор враждебных байтов не бросает ничего другого.
+ */
+export declare class PackError extends Error {
+    #private;
+    readonly code: PackErrorCode;
+    /** Field names and array indexes from the root down to the failing value. / Путь от корня до значения с ошибкой. */
+    readonly path: (string | number)[];
+    constructor(code: PackErrorCode, detail: string);
+    /** @internal Called while the error travels up through objects and arrays. */
+    addPath(segment: string | number): void;
+}
+/** @internal */
+export declare function fail(code: PackErrorCode, detail: string): never;