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

package/dist/errors.js

@@ -0,0 +1,33 @@
+/**
+ * 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 class PackError extends Error {
+    code;
+    /** Field names and array indexes from the root down to the failing value. / Путь от корня до значения с ошибкой. */
+    path = [];
+    #detail;
+    constructor(code, detail) {
+        super(detail);
+        this.name = 'PackError';
+        this.code = code;
+        this.#detail = detail;
+    }
+    /** @internal Called while the error travels up through objects and arrays. */
+    addPath(segment) {
+        this.path.unshift(segment);
+        this.message = `${this.#detail} (at ${formatPath(this.path)})`;
+    }
+}
+function formatPath(path) {
+    let out = '';
+    for (const seg of path)
+        out += typeof seg === 'number' ? `[${seg}]` : out ? `.${seg}` : seg;
+    return out;
+}
+/** @internal */
+export function fail(code, detail) {
+    throw new PackError(code, detail);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { PackError, type PackErrorCode } from './errors.js';
+export type { Codec, Infer, Value } from './codec.js';
+export { added, array, bool, bytes, define, enumOf, f32, f64, i16, i32, i64, i8, optional, quant, str, u16, u32, u64, u8, varint, varuint, type BytesOptions, type DefineOptions, type QuantOptions, type Shape, } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { PackError } from './errors.js';
+export { added, array, bool, bytes, define, enumOf, f32, f64, i16, i32, i64, i8, optional, quant, str, u16, u32, u64, u8, varint, varuint, } from './types.js';

package/dist/types.d.ts

@@ -0,0 +1,107 @@
+import { type Codec, type Value } from './codec.js';
+/** `true` / `false`, 1 byte. */
+export declare const bool: Codec<boolean>;
+/** Unsigned 8-bit integer. / Беззнаковое 8 бит. */
+export declare const u8: Codec<number>;
+/** Signed 8-bit integer. / Знаковое 8 бит. */
+export declare const i8: Codec<number>;
+/** Unsigned 16-bit integer, little-endian. / Беззнаковое 16 бит. */
+export declare const u16: Codec<number>;
+/** Signed 16-bit integer, little-endian. / Знаковое 16 бит. */
+export declare const i16: Codec<number>;
+/** Unsigned 32-bit integer, little-endian. / Беззнаковое 32 бита. */
+export declare const u32: Codec<number>;
+/** Signed 32-bit integer, little-endian. / Знаковое 32 бита. */
+export declare const i32: Codec<number>;
+/** Unsigned 64-bit integer, always a `bigint`. / Беззнаковое 64 бита, всегда `bigint`. */
+export declare const u64: Codec<bigint>;
+/** Signed 64-bit integer, always a `bigint`. / Знаковое 64 бита, всегда `bigint`. */
+export declare const i64: Codec<bigint>;
+/** IEEE 754 single precision. `NaN` and `±Infinity` survive. / Одинарная точность. */
+export declare const f32: Codec<number>;
+/** IEEE 754 double precision. `NaN` and `±Infinity` survive. / Двойная точность. */
+export declare const f64: Codec<number>;
+/** Unsigned LEB128, `0 … 2^32-1`, 1 to 5 bytes: small numbers cost one byte. / Малые числа занимают 1 байт. */
+export declare const varuint: Codec<number>;
+/** Zigzag + LEB128, `-2^31 … 2^31-1`: small magnitudes cost one byte whatever the sign. */
+export declare const varint: Codec<number>;
+/**
+ * UTF-8 string of at most `maxBytes` **bytes** (not characters). A longer string is an error, never truncated.
+ * Строка UTF-8 не длиннее `maxBytes` **байт** (не символов). Длиннее: ошибка, без обрезки.
+ */
+export declare function str(maxBytes: number): Codec<string>;
+export interface BytesOptions {
+    /**
+     * Return a view into the input instead of a copy. Zero-copy, but the result is only valid while the input
+     * buffer is not reused: network libraries often reuse theirs.
+     * Вернуть окно во входной буфер вместо копии. Без копирования, но результат живёт, пока вход не
+     * переиспользован (сетевые библиотеки часто переиспользуют свои буферы).
+     */
+    view?: boolean;
+}
+/**
+ * Raw bytes, at most `maxBytes`. Decoded as a copy by default.
+ * Сырые байты, не больше `maxBytes`. По умолчанию при чтении копируются.
+ */
+export declare function bytes(maxBytes: number, options?: BytesOptions): Codec<Uint8Array>;
+/**
+ * A list of `item`s, at most `maxCount` of them.
+ * Список из `item`, не больше `maxCount` штук.
+ */
+export declare function array<T>(item: Codec<T>, maxCount: number): Codec<T[]>;
+/**
+ * A value that may be absent: `undefined` (typed) or `null` (accepted at runtime, so JSON-shaped data works) when
+ * packing, `undefined` when unpacking. In `define`, the field may be left out. Costs 1 byte.
+ * Значение, которого может не быть: при упаковке `undefined` (по типам) или `null` (принимается в рантайме, чтобы
+ * данные из JSON не ломались), при чтении `undefined`. В `define` поле можно не указывать. Стоит 1 байт.
+ */
+export declare function optional<T>(item: Codec<T>): Codec<T | undefined>;
+/**
+ * One of a fixed list of names, stored as its index (1 byte for up to 256 names, else 2).
+ * Одно из имён фиксированного списка; хранится индексом (1 байт до 256 имён, иначе 2).
+ */
+export declare function enumOf<const N extends readonly string[]>(names: N): Codec<N[number]>;
+export interface QuantOptions {
+    /** Clamp out-of-range values into `[min, max]` instead of throwing. `NaN` always throws. */
+    clamp?: boolean;
+}
+/**
+ * A number in `[min, max]` stored as an unsigned `bits`-bit integer (8, 16 or 32): the error is at most half a
+ * step, `(max - min) / (2^bits - 1) / 2`. Positions, angles, ratios.
+ * Число из `[min, max]`, хранится беззнаковым целым в `bits` бит (8, 16 или 32): ошибка не больше полушага.
+ * Координаты, углы, доли.
+ */
+export declare function quant(min: number, max: number, bits: 8 | 16 | 32, options?: QuantOptions): Codec<number>;
+/** The shape passed to `define`: field name to codec. / Описание для `define`: имя поля, кодек. */
+export type Shape = Record<string, Codec<any>>;
+/**
+ * Mark a field of a record as added in a newer version of the schema. A packet written by an older writer ends
+ * before this field; then the reader fills it with `fallback`. The writer always writes it. Added fields must be
+ * the LAST fields of the record, and a record that has any can only be the top-level codec. See docs/spec.md,
+ * "Evolution".
+ * Пометить поле записи как добавленное в новой версии схемы. Пакет старого писателя кончается до этого поля,
+ * тогда читатель подставляет `fallback`. Писатель пишет его всегда. Добавленные поля должны идти ПОСЛЕДНИМИ,
+ * а запись с такими полями может быть только верхнего уровня. См. docs/spec.md, «Evolution».
+ */
+export declare function added<T>(item: Codec<T>, fallback: T): Codec<T>;
+export interface DefineOptions {
+    /**
+     * Off by default: a record is STRICT and any byte after its last field is an error. Turn this on to let the
+     * record's readers ignore bytes after the last field they know (fields a NEWER writer appended). Declare it
+     * from the first version of a message: a reader built without it rejects such packets. `added(...)` does not
+     * turn it on. Costs nothing on the wire; the price is that extra bytes are no longer reported as an error.
+     * Top-level codec only.
+     * По умолчанию выключено: запись СТРОГАЯ, любой байт после последнего поля это ошибка. Включите, чтобы
+     * читатели записи игнорировали байты после последнего известного поля (поля, дописанные БОЛЕЕ НОВЫМ
+     * писателем). Объявляйте с первой версии сообщения: читатель без этой опции такие пакеты отвергает.
+     * `added(...)` её не включает. На проводе бесплатно, но лишние байты больше не ошибка.
+     */
+    extensible?: boolean;
+}
+/**
+ * A record with named fields, written in declaration order. Names are not stored in the packet.
+ * Fields wrapped in `added(...)` (at the end) make it evolvable: see `added`.
+ * Запись с именованными полями, пишется в порядке объявления. Имена в пакет не попадают.
+ * Поля в `added(...)` (в конце) делают запись развиваемой: см. `added`.
+ */
+export declare function define<S extends Shape>(shape: S, options?: DefineOptions): Codec<Value<S>>;