@typeberry/lib 0.5.1-aff8b4f → 0.5.1-eb84786

package/packages/core/codec/decoder.test.js

@@ -0,0 +1,444 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { BitVec, Bytes, BytesBlob } from "#@typeberry/bytes";
+import { Decoder } from "./decoder.js";
+import * as codec from "./descriptors.js";
+import { Encoder } from "./encoder.js";
+function decodeVarU32(source, finish = true) {
+    const decoder = Decoder.fromBlob(source);
+    const value = decoder.varU32();
+    const bytesToSkip = decoder.bytesRead();
+    if (finish) {
+        decoder.finish();
+    }
+    // compare with u64 just to be sure.
+    const decoder2 = Decoder.fromBlob(source);
+    assert.strictEqual(decoder2.varU64(), BigInt(value));
+    if (finish) {
+        decoder2.finish();
+    }
+    return { value, bytesToSkip };
+}
+function decodeVarU64(source, finish = true) {
+    const decoder = Decoder.fromBlob(source);
+    const value = decoder.varU64();
+    const bytesToSkip = decoder.bytesRead();
+    if (finish) {
+        decoder.finish();
+    }
+    return { value, bytesToSkip };
+}
+describe("JAM decoder / finish", () => {
+    it("should fail when there are some bytes left", () => {
+        const encodedBytes = new Uint8Array([0]);
+        const decoder = Decoder.fromBlob(encodedBytes);
+        assert.throws(() => {
+            decoder.finish();
+        }, {
+            name: "Error",
+            message: "Expecting end of input, yet there are still 1 bytes left.",
+        });
+    });
+});
+describe("JAM decoder / natural number", () => {
+    it("should fail when there is not enough bytes for varU32", () => {
+        const encodedBytes = new Uint8Array([]);
+        const decoder = Decoder.fromBlob(encodedBytes);
+        assert.throws(() => {
+            decoder.varU32();
+        }, {
+            name: "Error",
+            message: "Attempting to decode more data than there is left. Need 1, left: 0.",
+        });
+    });
+    it("should fail when there is not enough bytes for varU64", () => {
+        const encodedBytes = new Uint8Array([240]);
+        const decoder = Decoder.fromBlob(encodedBytes);
+        assert.throws(() => {
+            decoder.varU64();
+        }, {
+            name: "Error",
+            message: "Attempting to decode more data than there is left. Need 4, left: 0.",
+        });
+    });
+    it("decode 0", () => {
+        const encodedBytes = new Uint8Array([0]);
+        const expectedValue = 0;
+        const result = decodeVarU32(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode single byte min value", () => {
+        const encodedBytes = new Uint8Array([1]);
+        const expectedValue = 1;
+        const result = decodeVarU32(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode single byte max value", () => {
+        const encodedBytes = new Uint8Array([127]);
+        const expectedValue = 127;
+        const result = decodeVarU32(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 2 bytes min value", () => {
+        const encodedBytes = new Uint8Array([128, 128]);
+        const expectedValue = 128;
+        const result = decodeVarU32(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 2 bytes max value", () => {
+        const encodedBytes = new Uint8Array([191, 255]);
+        const expectedValue = 2 ** 14 - 1;
+        const result = decodeVarU32(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 3 bytes min value", () => {
+        const encodedBytes = new Uint8Array([192, 0, 0x40]);
+        const expectedValue = 2 ** 14;
+        const result = decodeVarU32(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 3 bytes max value", () => {
+        const encodedBytes = new Uint8Array([192 + 31, 0xff, 0xff]);
+        const expectedValue = 2 ** 21 - 1;
+        const result = decodeVarU32(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 4 bytes min value", () => {
+        const encodedBytes = new Uint8Array([0xe0, 0, 0, 0x20]);
+        const expectedValue = 2 ** 21;
+        const result = decodeVarU32(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 4 bytes max value", () => {
+        const encodedBytes = new Uint8Array([0xe0 + 15, 0xff, 0xff, 0xff]);
+        const expectedValue = 2 ** 28 - 1;
+        const result = decodeVarU32(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 5 bytes min value", () => {
+        const encodedBytes = new Uint8Array([256 - 16, 0, 0, 0, 0x10]);
+        const expectedValue = 2n ** 28n;
+        const result = decodeVarU64(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 5 bytes max value", () => {
+        const encodedBytes = new Uint8Array([256 - 16 + 7, 0xff, 0xff, 0xff, 0xff]);
+        const expectedValue = 2n ** 35n - 1n;
+        const result = decodeVarU64(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 6 bytes min value", () => {
+        const encodedBytes = new Uint8Array([256 - 8, 0, 0, 0, 0, 0x08]);
+        const expectedValue = 2n ** 35n;
+        const result = decodeVarU64(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 6 bytes max value", () => {
+        const encodedBytes = new Uint8Array([256 - 8 + 3, 0xff, 0xff, 0xff, 0xff, 0xff]);
+        const expectedValue = 2n ** 42n - 1n;
+        const result = decodeVarU64(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 7 bytes min value", () => {
+        const encodedBytes = new Uint8Array([256 - 4, 0, 0, 0, 0, 0, 0x04]);
+        const expectedValue = 2n ** 42n;
+        const result = decodeVarU64(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 7 bytes max value", () => {
+        const encodedBytes = new Uint8Array([256 - 4 + 1, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff]);
+        const expectedValue = 2n ** 49n - 1n;
+        const result = decodeVarU64(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 8 bytes min value", () => {
+        const encodedBytes = new Uint8Array([256 - 2, 0, 0, 0, 0, 0, 0, 0x02]);
+        const expectedValue = 2n ** 49n;
+        const result = decodeVarU64(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 8 bytes max value", () => {
+        const encodedBytes = new Uint8Array([256 - 2, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff]);
+        const expectedValue = 2n ** 56n - 1n;
+        const result = decodeVarU64(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 9 bytes min value", () => {
+        const encodedBytes = new Uint8Array([255, 0, 0, 0, 0, 0, 0, 0, 0x01]);
+        const expectedValue = 2n ** 56n;
+        const result = decodeVarU64(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 9 bytes max value", () => {
+        const encodedBytes = new Uint8Array([255, 255, 255, 255, 255, 255, 255, 255, 255]);
+        const expectedValue = 2n ** 64n - 1n;
+        const result = decodeVarU64(encodedBytes);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, encodedBytes.length);
+    });
+    it("decode 0 with extra bytes", () => {
+        const encodedBytes = new Uint8Array([0, 1, 2, 3]);
+        const expectedValue = 0;
+        const result = decodeVarU32(encodedBytes, false);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, 1);
+    });
+    it("decode 7 bytes number with extra bytes ", () => {
+        const encodedBytes = new Uint8Array([256 - 4 + 1, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x1, 0x2]);
+        const expectedValue = 2n ** 49n - 1n;
+        const result = decodeVarU64(encodedBytes, false);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, 7);
+    });
+    it("decode 9 bytes number with extra bytes", () => {
+        const encodedBytes = new Uint8Array([255, 255, 255, 255, 255, 255, 255, 255, 255, 1, 2, 3]);
+        const expectedValue = 2n ** 64n - 1n;
+        const result = decodeVarU64(encodedBytes, false);
+        assert.strictEqual(result.value, expectedValue);
+        assert.strictEqual(result.bytesToSkip, 9);
+    });
+});
+describe("JAM decoder / bytes", () => {
+    it("should decode empty bytes sequence", () => {
+        const input = BytesBlob.parseBlob("0x00");
+        const decoder = Decoder.fromBytesBlob(input);
+        const blob = decoder.bytesBlob();
+        decoder.finish();
+        assert.deepStrictEqual(blob.toString(), "0x");
+    });
+    it("should decode bytes sequence", () => {
+        const input = BytesBlob.parseBlob("0x04deadbeef");
+        const decoder = Decoder.fromBytesBlob(input);
+        const blob = decoder.bytesBlob();
+        decoder.finish();
+        assert.deepStrictEqual(blob.toString(), "0xdeadbeef");
+    });
+    it("should decode a fixed-length bytes", () => {
+        const input = BytesBlob.parseBlob("0xdeadbeef");
+        const decoder = Decoder.fromBytesBlob(input);
+        const blob = decoder.bytes(4);
+        decoder.finish();
+        assert.deepStrictEqual(blob.toString(), "0xdeadbeef");
+    });
+});
+describe("JAM decoder / numbers", () => {
+    it("should decode a large number", () => {
+        const input = BytesBlob.parseBlob("0xf0ffffffff");
+        const decoder = Decoder.fromBytesBlob(input);
+        const l = decoder.varU32();
+        decoder.resetTo(0);
+        const ln = decoder.varU64();
+        decoder.finish();
+        assert.deepStrictEqual(BigInt(l), ln);
+        assert.deepStrictEqual(l, 2 ** 32 - 1);
+    });
+    it("should fail to decode a number over 32-bits", () => {
+        const input = BytesBlob.parseBlob("0xf100000000");
+        const decoder = Decoder.fromBytesBlob(input);
+        const ln = decoder.varU64();
+        assert.deepStrictEqual(ln, 2n ** 32n);
+        decoder.resetTo(0);
+        assert.throws(() => decoder.varU32(), {
+            name: "Error",
+            message: "Unexpectedly large value for u32. l=4, mostSignificantByte=1",
+        });
+    });
+    it("should decode variable length u32", () => {
+        const input = BytesBlob.parseBlob("0x000102032af0fffffffff0ffffff7ff042424242");
+        const decoder = Decoder.fromBytesBlob(input);
+        assert.deepStrictEqual(decoder.varU32(), 0);
+        assert.deepStrictEqual(decoder.varU32(), 1);
+        assert.deepStrictEqual(decoder.varU32(), 2);
+        assert.deepStrictEqual(decoder.varU32(), 3);
+        assert.deepStrictEqual(decoder.varU32(), 42);
+        assert.deepStrictEqual(decoder.varU32(), 2 ** 32 - 1);
+        assert.deepStrictEqual(decoder.varU32(), 2 ** 31 - 1);
+        assert.deepStrictEqual(decoder.varU32(), 0x42424242);
+        decoder.finish();
+    });
+    it("should decode variable length u64", () => {
+        const input = BytesBlob.parseBlob("0x0001f100000000ff0000000000000001ffffffffffffffffff");
+        const decoder = Decoder.fromBytesBlob(input);
+        assert.deepStrictEqual(decoder.varU64(), 0n);
+        assert.deepStrictEqual(decoder.varU64(), 1n);
+        assert.deepStrictEqual(decoder.varU64(), 2n ** 32n);
+        assert.deepStrictEqual(decoder.varU64(), 2n ** 56n);
+        assert.deepStrictEqual(decoder.varU64(), 2n ** 64n - 1n);
+        decoder.finish();
+    });
+    it("should decode a bunch of i64 numbers", () => {
+        const input = BytesBlob.parseBlob("0xffffffffffffff7f00000000000000804242424200000000d6ffffffffffffff0000000000000000");
+        const decoder = Decoder.fromBytesBlob(input);
+        const results = [decoder.i64(), decoder.i64(), decoder.i64(), decoder.i64(), decoder.i64()];
+        decoder.finish();
+        assert.deepStrictEqual(results, [2n ** 63n - 1n, -(2n ** 63n), 0x42424242n, -42n, 0n]);
+    });
+    it("should decode a bunch of i32 numbers", () => {
+        const input = BytesBlob.parseBlob("0xffffff7f0000008042424242d6ffffff00000000");
+        const decoder = Decoder.fromBytesBlob(input);
+        const results = [decoder.i32(), decoder.i32(), decoder.i32(), decoder.i32(), decoder.i32()];
+        decoder.finish();
+        assert.deepStrictEqual(results, [2 ** 31 - 1, -(2 ** 31), 0x42424242, -42, 0]);
+    });
+    it("should decode a bunch of u32 numbers", () => {
+        const input = BytesBlob.parseBlob("0xffffff7f0000008042424242d6ffffff00000000");
+        const decoder = Decoder.fromBytesBlob(input);
+        const results = [decoder.u32(), decoder.u32(), decoder.u32(), decoder.u32(), decoder.u32()];
+        decoder.finish();
+        assert.deepStrictEqual(results, [2 ** 31 - 1, 2 ** 32 - 2 ** 31, 0x42424242, 2 ** 32 - 42, 0]);
+    });
+    it("should decode a bunch of i24 numbers", () => {
+        const input = BytesBlob.parseBlob("0x424242d6ffff00000081ffff811c15000080ffff7f010080");
+        const decoder = Decoder.fromBytesBlob(input);
+        assert.deepStrictEqual(decoder.i24(), 0x424242);
+        assert.deepStrictEqual(decoder.i24(), -42);
+        assert.deepStrictEqual(decoder.i24(), 0);
+        assert.deepStrictEqual(decoder.i24(), -127);
+        assert.deepStrictEqual(decoder.i24(), 1383553);
+        assert.deepStrictEqual(decoder.i24(), -(2 ** 23));
+        assert.deepStrictEqual(decoder.i24(), 2 ** 23 - 1);
+        assert.deepStrictEqual(decoder.i24(), -(2 ** 23 - 1));
+        decoder.finish();
+    });
+    it("should decode a bunch of i16 numbers", () => {
+        const input = BytesBlob.parseBlob("0x4242d6ff0000");
+        const decoder = Decoder.fromBytesBlob(input);
+        const results = [decoder.i16(), decoder.i16(), decoder.i16()];
+        decoder.finish();
+        assert.deepStrictEqual(results, [0x4242, -42, 0]);
+    });
+    it("should decode a bunch of i8 numbers", () => {
+        const input = BytesBlob.parseBlob("0x42d600");
+        const decoder = Decoder.fromBytesBlob(input);
+        const results = [decoder.i8(), decoder.i8(), decoder.i8()];
+        decoder.finish();
+        assert.deepStrictEqual(results, [0x42, -42, 0]);
+    });
+    it("should decode a bool", () => {
+        const input = BytesBlob.parseBlob("0x0100");
+        const decoder = Decoder.fromBytesBlob(input);
+        assert.deepStrictEqual(decoder.bool(), true);
+        assert.deepStrictEqual(decoder.bool(), false);
+        decoder.finish();
+    });
+});
+describe("JAM decoder / bitvec", () => {
+    it("should decode a 1-byte bit vector", () => {
+        const input = BytesBlob.parseBlob("0x410841");
+        const decoder = Decoder.fromBytesBlob(input);
+        // when
+        const bitvec1 = decoder.bitVecFixLen(8);
+        const bitvec2 = decoder.bitVecVarLen();
+        decoder.finish();
+        // then
+        const expected = BitVec.empty(8);
+        expected.setBit(0, true);
+        expected.setBit(6, true);
+        assert.deepStrictEqual(bitvec1, expected);
+        assert.deepStrictEqual(bitvec2, expected);
+    });
+    it("should decode a longer bit vector", () => {
+        const input = BytesBlob.parseBlob("0x01000000010000800141010000000100008001");
+        const decoder = Decoder.fromBytesBlob(input);
+        // when
+        const bitvec1 = decoder.bitVecFixLen(65);
+        const bitvec2 = decoder.bitVecVarLen();
+        decoder.finish();
+        // then
+        const expected = BitVec.empty(65);
+        expected.setBit(0, true);
+        expected.setBit(32, true);
+        expected.setBit(63, true);
+        expected.setBit(64, true);
+        assert.deepStrictEqual(bitvec1, expected);
+        assert.deepStrictEqual(bitvec2, expected);
+    });
+    it("should fail if remaining bits are set", () => {
+        const input = BytesBlob.parseBlob("0x010000000100008011");
+        const decoder = Decoder.fromBytesBlob(input);
+        // when
+        assert.throws(() => decoder.bitVecFixLen(65), {
+            name: "Error",
+            message: "Non-zero bits found in the last byte of bitvec encoding.",
+        });
+    });
+});
+describe("JAM decoder / generics", () => {
+    class MyType {
+        x;
+        y;
+        z;
+        constructor(x, y, z) {
+            this.x = x;
+            this.y = y;
+            this.z = z;
+        }
+        static decode(decoder) {
+            const x = decoder.i32();
+            const y = decoder.bool();
+            const z = decoder.bytes(4);
+            return new MyType(x, y, z);
+        }
+    }
+    it("should decode an optional value", () => {
+        const input = BytesBlob.parseBlob("0x010300000001deadbeef0000010500000000deadbeef");
+        const decoder = Decoder.fromBytesBlob(input);
+        const results = [
+            decoder.optional(MyType),
+            decoder.optional(MyType),
+            decoder.optional(MyType),
+            decoder.optional(MyType),
+        ];
+        decoder.finish();
+        assert.deepStrictEqual(results, [
+            new MyType(3, true, Bytes.parseBytes("0xdeadbeef", 4)),
+            null,
+            null,
+            new MyType(5, false, Bytes.parseBytes("0xdeadbeef", 4)),
+        ]);
+    });
+    it("should decode a sequence", () => {
+        const input = BytesBlob.parseBlob("0x030500000001deadbeef0700000001deadbeef0a00000001deadbeef0500000001deadbeef0700000001deadbeef0a00000001deadbeef");
+        const decoder = Decoder.fromBytesBlob(input);
+        const result1 = decoder.sequenceVarLen(MyType);
+        const result2 = decoder.sequenceFixLen(MyType, 3);
+        decoder.finish();
+        const bytes = Bytes.parseBytes("0xdeadbeef", 4);
+        const expected = [new MyType(5, true, bytes), new MyType(7, true, bytes), new MyType(10, true, bytes)];
+        assert.deepStrictEqual(result1, expected);
+        assert.deepStrictEqual(result2, expected);
+    });
+});
+describe("JAM decoder / decodeSequence", () => {
+    const data = ["is", "there", "anybody", "out", "there", "?"];
+    const encodedData = Encoder.encodeObject(codec.sequenceFixLen(codec.string, data.length), data);
+    it("should decode a sequence of unknown length", () => {
+        assert.deepStrictEqual(Decoder.decodeSequence(codec.string, encodedData), data);
+    });
+    it("should throw an error when data is invalid", () => {
+        const invalidData = BytesBlob.parseBlob("0xf60587061670964567267744557f1270333e84696620669775705265f6");
+        assert.throws(() => Decoder.decodeSequence(codec.string, invalidData), Error);
+    });
+    it("should throw an error when there's extra data past valid data", () => {
+        const dataWithExtraData = Bytes.parseBlob(`${encodedData.toString()}deadbeef`);
+        assert.throws(() => Decoder.decodeSequence(codec.string, dataWithExtraData), Error);
+    });
+});

package/packages/core/codec/descriptor.d.ts

@@ -0,0 +1,86 @@
+import { BytesBlob } from "#@typeberry/bytes";
+import { type Opaque, type TokenOf } from "#@typeberry/utils";
+import type { Decode, Decoder } from "./decoder.js";
+import type { Encode, Encoder, SizeHint } from "./encoder.js";
+import { type Skip, Skipper } from "./skip.js";
+/** Infer the type that is described by given descriptor `T` */
+export type DescribedBy<T> = T extends Descriptor<infer V, infer _> ? V : never;
+/**
+ * Converts a class `T` into an object with the same fields as the class.
+ */
+export type CodecRecord<T> = {
+    [K in PropertyKeys<T>]: T[K];
+};
+/**
+ * Same as `CodecRecord<T>`, but the fields are all optional.
+ */
+export type OptionalRecord<T> = {
+    [K in PropertyKeys<T>]?: T[K];
+};
+/**
+ * `Descriptor` of a complex type of some class with a bunch of public fields.
+ */
+export type DescriptorRecord<T> = {
+    [K in PropertyKeys<T>]: Descriptor<T[K], unknown>;
+};
+/**
+ * Simplified `DescriptorRecord`, where all keys must be used as descriptor keys.
+ */
+export type SimpleDescriptorRecord<T> = {
+    [K in keyof T]: Descriptor<T[K], unknown>;
+};
+/** Only keys that contain properties, not methods. */
+export type PropertyKeys<T> = {
+    [K in Extract<keyof T, string>]: T[K] extends Function ? never : K;
+}[Extract<keyof T, string>];
+/** A constructor of basic data object that takes a `Record<T>`. */
+export type ClassConstructor<T> = {
+    name: string;
+    create: (o: CodecRecord<T>) => T;
+};
+/** A full codec type, i.e. the `Encode` and `Decode`. */
+export type Codec<T> = Encode<T> & Decode<T>;
+/** A codec descriptor with extra view. */
+export interface CodecWithView<T, V> extends Codec<T> {
+    /** encoded data view codec. */
+    View: Codec<V>;
+}
+/**
+ * Type descriptor definition.
+ *
+ * The type descriptor can encode & decode given type `T`, but
+ * also have a `name` and a byte-size hint.
+ *
+ * Descriptors can be composed to form more complex typings.
+ */
+export declare class Descriptor<T, V = T> implements Codec<T>, Skip, CodecWithView<T, V> {
+    /** Descriptive name of the coded data. */
+    readonly name: string;
+    /** A byte size hint for encoded data. */
+    readonly sizeHint: SizeHint;
+    /** Encoding function. */
+    readonly encode: (e: Encoder, elem: T) => void;
+    /** Decoding function. */
+    readonly decode: (d: Decoder) => T;
+    /** Skipping function. */
+    readonly skip: (s: Skipper) => void;
+    /** A "lightweight" version of the object. */
+    readonly View: Descriptor<V>;
+    /** New descriptor with specialized `View`. */
+    static withView<T, V>(name: string, sizeHint: SizeHint, encode: Descriptor<T, V>["encode"], decode: Descriptor<T, V>["decode"], skip: Descriptor<T, V>["skip"], view: Descriptor<V>): Descriptor<T, V>;
+    /** Create a new descriptor without a specialized `View`. */
+    static new<T>(name: string, sizeHint: SizeHint, encode: Descriptor<T>["encode"], decode: Descriptor<T>["decode"], skip: Descriptor<T>["skip"]): Descriptor<T, T>;
+    private constructor();
+    /**
+     * Extract an encoded version of this type from the decoder.
+     *
+     * This function skips the object instead of decoding it,
+     * allowing to retrieve the encoded portion of the object from `Decoder`.
+     */
+    skipEncoded(decoder: Decoder): BytesBlob;
+    /** Return a new descriptor that converts data into some other type. */
+    convert<F>(input: (i: F) => T, output: (i: T) => F): Descriptor<F, V>;
+    /** Safely cast the descriptor value to a opaque type. */
+    asOpaque<R>(): Descriptor<Opaque<T, TokenOf<R, T>>, V>;
+}
+//# sourceMappingURL=descriptor.d.ts.map

package/packages/core/codec/descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../../../../../packages/core/codec/descriptor.ts"],"names":[],"mappings":"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"}

package/packages/core/codec/descriptor.js

@@ -0,0 +1,69 @@
+import { BytesBlob } from "#@typeberry/bytes";
+import { asOpaqueType, seeThrough } from "#@typeberry/utils";
+import { Skipper } from "./skip.js";
+/**
+ * Type descriptor definition.
+ *
+ * The type descriptor can encode & decode given type `T`, but
+ * also have a `name` and a byte-size hint.
+ *
+ * Descriptors can be composed to form more complex typings.
+ */
+export class Descriptor {
+    name;
+    sizeHint;
+    encode;
+    decode;
+    skip;
+    /** A "lightweight" version of the object. */
+    View;
+    /** New descriptor with specialized `View`. */
+    static withView(name, sizeHint, encode, decode, skip, view) {
+        return new Descriptor(name, sizeHint, encode, decode, skip, view);
+    }
+    /** Create a new descriptor without a specialized `View`. */
+    static new(name, sizeHint, encode, decode, skip) {
+        return new Descriptor(name, sizeHint, encode, decode, skip, null);
+    }
+    constructor(
+    /** Descriptive name of the coded data. */
+    name, 
+    /** A byte size hint for encoded data. */
+    sizeHint, 
+    /** Encoding function. */
+    encode, 
+    /** Decoding function. */
+    decode, 
+    /** Skipping function. */
+    skip, 
+    /** view object. It can be `null` iff T===V. */
+    view) {
+        this.name = name;
+        this.sizeHint = sizeHint;
+        this.encode = encode;
+        this.decode = decode;
+        this.skip = skip;
+        // We cast here to make sure that the field is always set.
+        this.View = view ?? this;
+    }
+    /**
+     * Extract an encoded version of this type from the decoder.
+     *
+     * This function skips the object instead of decoding it,
+     * allowing to retrieve the encoded portion of the object from `Decoder`.
+     */
+    skipEncoded(decoder) {
+        const initBytes = decoder.bytesRead();
+        this.skip(new Skipper(decoder));
+        const endBytes = decoder.bytesRead();
+        return BytesBlob.blobFrom(decoder.source.subarray(initBytes, endBytes));
+    }
+    /** Return a new descriptor that converts data into some other type. */
+    convert(input, output) {
+        return new Descriptor(this.name, this.sizeHint, (e, elem) => this.encode(e, input(elem)), (d) => output(this.decode(d)), this.skip, this.View);
+    }
+    /** Safely cast the descriptor value to a opaque type. */
+    asOpaque() {
+        return this.convert((i) => seeThrough(i), (o) => asOpaqueType(o));
+    }
+}