@leofcoin/binary 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @leofcoin/binary
 
-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.
+`@leofcoin/binary` is a dependency-free shared implementation of unsigned
+base-128 integers and length-prefixed byte frames. Numeric values retain the
+existing wire bytes. No chain field, codec identifier, hash algorithm or supply
+representation changes as part of this migration.
+
+It is independent of `@leofcoin/codecs`, which remains the registry of codec
+identifiers. This package does not import or re-export that registry.
+
+```js
+import { BinaryReader, BinaryWriter, varUintLength } from '@leofcoin/binary'
+
+const signature = new Uint8Array(64)
+const writer = new BinaryWriter(varUintLength(1) + varUintLength(129) + signature.length)
+writer.writeVarUint(1).writeVarUint(129).writeBytes(signature)
+const reader = new BinaryReader(writer.finish())
+const version = reader.readVarUint()
+const codec = reader.readVarUint()
+const decodedSignature = reader.readBytes(reader.remaining)
+```
+
+- `writeVarUint` / `readVarUint`: unsigned safe-integer Numbers, at most 8 bytes.
+- `writeVarBigInt` / `readVarBigInt`: unsigned BigInts through `2^256-1`, at most 37 bytes.
+- `writeFrame` / `readFrame`: Number length prefix plus bytes. A failed operation
+  does not advance the cursor. Writes check capacity before changing bytes.
+- `encodeFrames` / `decodeFrames`: a sequence of those frames; optional raw prefix
+  bytes on encode, corresponding prefix length on decode. Encoding allocates one
+  output buffer, without allocating a varint array for every field. Decoding is
+  iterative, so many fields do not exhaust the call stack.
+
+Readers return **views**, not copies; modifying a view modifies the input buffer.
+`writer.finish()` likewise returns a view. Use `finish(true)` to retain an
+independent copy before resetting/reusing a writer. Writers have fixed capacity;
+the caller supplies the capacity or an existing Uint8Array. There is no hidden
+buffer growth or mutable process-global `.bytes` state.
+
+New reader calls reject padded/non-canonical integers by default. Existing block
+validator framing explicitly uses `canonical: false` to preserve legacy padded
+prefix acceptance. Tightening that consensus rule needs a separate protocol
+decision. Overflow and truncated fields still fail closed. `decodeFrames` accepts
+an optional `maxFrames` policy; network size/membership limits remain the caller's
+responsibility. BigInt support does not automatically migrate existing fields.
+
+Checks: `npm test -w @leofcoin/binary`, `npm test -w @leofcoin/messages`.
+Benchmark: `node test/bench/binary-codec.js`. It compares the actual installed
+legacy framing packages and verifies equal bytes before measuring. Results are
+local CPU timings, not blockchain throughput or transport latency claims.

package/exports/index.d.ts

@@ -0,0 +1,34 @@
+export declare function varUintLength(value: number): number;
+export declare function varBigIntLength(value: bigint): number;
+/** Fixed-capacity writer. finish() is a view; copy it before reusing/resetting the writer. */
+export declare class BinaryWriter {
+    #private;
+    constructor(capacity?: number | Uint8Array);
+    get position(): number;
+    get remaining(): number;
+    writeVarUint(value: number): this;
+    writeVarBigInt(value: bigint): this;
+    writeBytes(value: Uint8Array): this;
+    writeFrame(value: Uint8Array): this;
+    reset(): this;
+    finish(copy?: boolean): Uint8Array;
+}
+/** Reads views of the original buffer. Failed operations leave the cursor unchanged. */
+export declare class BinaryReader {
+    #private;
+    constructor(buffer: Uint8Array);
+    get position(): number;
+    get remaining(): number;
+    readVarUint(canonical?: boolean): number;
+    readVarBigInt(canonical?: boolean): bigint;
+    readBytes(length: number): Uint8Array;
+    readFrame(canonical?: boolean): Uint8Array;
+}
+/** Existing smart-concat bytes, with exactly one output allocation and no prefix arrays. */
+export declare function encodeFrames(frames: readonly Uint8Array[], prefix?: Uint8Array): Uint8Array;
+export interface FrameOptions {
+    canonical?: boolean;
+    maxFrames?: number;
+}
+/** Iterative framing: bounded by the input length, not recursive stack depth. */
+export declare function decodeFrames(buffer: Uint8Array, prefixLength?: number, options?: FrameOptions): Uint8Array[];

package/exports/index.js

@@ -0,0 +1,216 @@
+/** @leofcoin/binary: dependency-free unsigned framing, with no global byte counters. */
+const MAX_BIGINT = (1n << 256n) - 1n;
+function size(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new RangeError('Expected an unsigned safe integer');
+}
+function bytes(value) {
+    if (!(value instanceof Uint8Array))
+        throw new TypeError('Expected Uint8Array');
+}
+export function varUintLength(value) {
+    size(value);
+    let length = 1;
+    while (value >= 128) {
+        value = Math.floor(value / 128);
+        length++;
+    }
+    return length;
+}
+export function varBigIntLength(value) {
+    if (typeof value !== 'bigint')
+        throw new TypeError('Expected BigInt');
+    if (value < 0n || value > MAX_BIGINT)
+        throw new RangeError('Expected an unsigned 256-bit integer');
+    let length = 1;
+    while (value >= 128n) {
+        value >>= 7n;
+        length++;
+    }
+    return length;
+}
+/** Fixed-capacity writer. finish() is a view; copy it before reusing/resetting the writer. */
+export class BinaryWriter {
+    #buffer;
+    #position = 0;
+    constructor(capacity = 64) {
+        if (typeof capacity === 'number') {
+            size(capacity);
+            this.#buffer = new Uint8Array(capacity);
+        }
+        else {
+            bytes(capacity);
+            this.#buffer = capacity;
+        }
+    }
+    get position() {
+        return this.#position;
+    }
+    get remaining() {
+        return this.#buffer.length - this.#position;
+    }
+    #require(length) {
+        size(length);
+        if (length > this.remaining)
+            throw new RangeError('Binary output buffer is too small');
+    }
+    writeVarUint(value) {
+        this.#require(varUintLength(value));
+        this.#writeVarUint(value);
+        return this;
+    }
+    #writeVarUint(value) {
+        while (value >= 128) {
+            this.#buffer[this.#position++] = value % 128 | 128;
+            value = Math.floor(value / 128);
+        }
+        this.#buffer[this.#position++] = value;
+    }
+    writeVarBigInt(value) {
+        this.#require(varBigIntLength(value));
+        do {
+            const byte = Number(value & 127n);
+            value >>= 7n;
+            this.#buffer[this.#position++] = byte | (value ? 128 : 0);
+        } while (value);
+        return this;
+    }
+    writeBytes(value) {
+        bytes(value);
+        this.#require(value.length);
+        this.#buffer.set(value, this.#position);
+        this.#position += value.length;
+        return this;
+    }
+    writeFrame(value) {
+        bytes(value);
+        // Check the complete operation before writing its length prefix.
+        const prefixLength = varUintLength(value.length);
+        this.#require(prefixLength + value.length);
+        const prefixStart = this.#buffer.byteOffset + this.#position;
+        if (value.buffer === this.#buffer.buffer &&
+            value.byteOffset < prefixStart + prefixLength &&
+            value.byteOffset + value.length > prefixStart)
+            throw new RangeError('Frame source overlaps its length prefix');
+        this.#writeVarUint(value.length);
+        this.#buffer.set(value, this.#position);
+        this.#position += value.length;
+        return this;
+    }
+    reset() {
+        this.#position = 0;
+        return this;
+    }
+    finish(copy = false) {
+        const result = this.#buffer.subarray(0, this.#position);
+        // Buffer.slice() aliases memory; this constructor copies every Uint8Array subtype.
+        return copy ? new Uint8Array(result) : result;
+    }
+}
+/** Reads views of the original buffer. Failed operations leave the cursor unchanged. */
+export class BinaryReader {
+    #buffer;
+    #position = 0;
+    constructor(buffer) {
+        bytes(buffer);
+        this.#buffer = buffer;
+    }
+    get position() {
+        return this.#position;
+    }
+    get remaining() {
+        return this.#buffer.length - this.#position;
+    }
+    readVarUint(canonical = true) {
+        let result = 0;
+        let multiplier = 1;
+        for (let index = 0; index < 8; index++) {
+            const cursor = this.#position + index;
+            if (cursor >= this.#buffer.length)
+                throw new RangeError('Truncated varint');
+            const byte = this.#buffer[cursor];
+            const payload = byte & 127;
+            if (index === 7 && payload > Math.floor((Number.MAX_SAFE_INTEGER - result) / multiplier))
+                throw new RangeError('Varint exceeds safe integer range');
+            result += payload * multiplier;
+            if (byte < 128) {
+                if (canonical && index > 0 && payload === 0)
+                    throw new RangeError('Non-canonical varint');
+                this.#position = cursor + 1;
+                return result;
+            }
+            multiplier *= 128;
+        }
+        throw new RangeError('Varint exceeds safe integer range');
+    }
+    readVarBigInt(canonical = true) {
+        let result = 0n;
+        for (let index = 0; index < 37; index++) {
+            const cursor = this.#position + index;
+            if (cursor >= this.#buffer.length)
+                throw new RangeError('Truncated varint');
+            const byte = this.#buffer[cursor];
+            result |= BigInt(byte & 127) << BigInt(index * 7);
+            if (result > MAX_BIGINT)
+                throw new RangeError('Varint exceeds 256 bits');
+            if (byte < 128) {
+                if (canonical && index > 0 && byte === 0)
+                    throw new RangeError('Non-canonical varint');
+                this.#position = cursor + 1;
+                return result;
+            }
+        }
+        throw new RangeError('Varint exceeds 256 bits');
+    }
+    readBytes(length) {
+        size(length);
+        if (length > this.remaining)
+            throw new RangeError('Truncated binary field');
+        const start = this.#position;
+        this.#position += length;
+        return this.#buffer.subarray(start, this.#position);
+    }
+    readFrame(canonical = true) {
+        const start = this.#position;
+        try {
+            return this.readBytes(this.readVarUint(canonical));
+        }
+        catch (error) {
+            this.#position = start;
+            throw error;
+        }
+    }
+}
+/** Existing smart-concat bytes, with exactly one output allocation and no prefix arrays. */
+export function encodeFrames(frames, prefix) {
+    if (!Array.isArray(frames))
+        throw new TypeError('Expected an array of byte frames');
+    if (prefix !== undefined)
+        bytes(prefix);
+    let length = prefix?.length ?? 0;
+    for (const frame of frames) {
+        bytes(frame);
+        length += varUintLength(frame.length) + frame.length;
+        size(length);
+    }
+    const writer = new BinaryWriter(length);
+    if (prefix)
+        writer.writeBytes(prefix);
+    for (const frame of frames)
+        writer.writeFrame(frame);
+    return writer.finish();
+}
+/** Iterative framing: bounded by the input length, not recursive stack depth. */
+export function decodeFrames(buffer, prefixLength = 0, options = {}) {
+    const reader = new BinaryReader(buffer);
+    reader.readBytes(prefixLength);
+    const maxFrames = options.maxFrames ?? buffer.length;
+    size(maxFrames);
+    const frames = [];
+    while (reader.remaining) {
+        if (frames.length >= maxFrames)
+            throw new RangeError('Too many binary frames');
+        frames.push(reader.readFrame(options.canonical ?? true));
+    }
+    return frames;
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@leofcoin/binary",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Dependency-free binary Reader/Writer, unsigned varints and byte framing",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./exports/index.js",
+      "types": "./exports/index.d.ts"
+    }
+  },
+  "files": [
+    "exports",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc6 -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "node --test"
+  },
+  "devDependencies": {
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/leofcoin/monorepo.git",
+    "directory": "packages/binary"
+  }
+}