@typeberry/lib 0.5.1-a4d7c93 → 0.5.1-eb84786

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

@@ -0,0 +1,123 @@
+import { type BitVec, Bytes, BytesBlob } from "#@typeberry/bytes";
+import { type U8, type U16, type U32, type U64 } from "#@typeberry/numbers";
+import { type Decoder } from "./decoder.js";
+import { type ClassConstructor, type CodecRecord, Descriptor, type DescriptorRecord, type SimpleDescriptorRecord } from "./descriptor.js";
+import { type Encoder, type SizeHint } from "./encoder.js";
+import { Skipper } from "./skip.js";
+import { type LengthRange } from "./validation.js";
+import { SequenceView, type ViewOf } from "./view.js";
+/**
+ * For the size hint for encoding typical dictionaries.
+ * TODO [ToDr] [opti] This value should be updated when we run some real-data bechmarks.
+ */
+export declare const TYPICAL_DICTIONARY_LENGTH = 32;
+/**
+ * Convert a descriptor for regular array into readonly one.
+ *
+ * NOTE: for performance reasons we assume that every `readonly T[]` is `T[]`,
+ *       and the `readonly` annotation is there just to prevent altering it.
+ *       It's not true in a general case, but should be good enough for us.
+ *
+ */
+export declare function readonlyArray<T, V>(desc: Descriptor<T[], V>): Descriptor<readonly T[], V>;
+/** Fixed-length bytes sequence. */
+export declare const bytes: <N extends number>(len: N) => Descriptor<Bytes<N>>;
+/** Zero-size `void` value. */
+export declare const nothing: Descriptor<void, void>;
+/** Variable-length U32. */
+export declare const varU32: Descriptor<U32, U32>;
+/** Variable-length U64. */
+export declare const varU64: Descriptor<U64, U64>;
+/** Unsigned 64-bit number. */
+export declare const u64: Descriptor<U64, Bytes<8>>;
+/** Unsigned 32-bit number. */
+export declare const u32: Descriptor<U32, Bytes<4>>;
+/** Unsigned 24-bit number. */
+export declare const u24: Descriptor<number, Bytes<3>>;
+/** Unsigned 16-bit number. */
+export declare const u16: Descriptor<U16, Bytes<2>>;
+/** Unsigned 8-bit number. */
+export declare const u8: Descriptor<U8, U8>;
+/** Signed 64-bit number. */
+export declare const i64: Descriptor<bigint, Bytes<8>>;
+/** Signed 32-bit number. */
+export declare const i32: Descriptor<number, Bytes<4>>;
+/** Signed 24-bit number. */
+export declare const i24: Descriptor<number, Bytes<3>>;
+/** Signed 16-bit number. */
+export declare const i16: Descriptor<number, Bytes<2>>;
+/** Signed 8-bit number. */
+export declare const i8: Descriptor<number, number>;
+/** 1-byte boolean value. */
+export declare const bool: Descriptor<boolean, boolean>;
+/** Variable-length bytes blob. */
+export declare const blob: Descriptor<BytesBlob, BytesBlob>;
+/** String encoded as variable-length bytes blob. */
+export declare const string: Descriptor<string, BytesBlob>;
+/** Variable-length bit vector. */
+export declare const bitVecVarLen: Descriptor<BitVec, BitVec>;
+/** Fixed-length bit vector. */
+export declare const bitVecFixLen: (bitLen: number) => Descriptor<BitVec, BitVec>;
+/** Optionality wrapper for given type. */
+export declare const optional: <T, V>(type: Descriptor<T, V>) => Descriptor<T | null, V | null>;
+export type SequenceVarLenOptions = LengthRange & {
+    typicalLength?: number;
+};
+/** Variable-length sequence of given type. */
+export declare const sequenceVarLen: <T, V = T>(type: Descriptor<T, V>, options?: SequenceVarLenOptions) => Descriptor<T[], SequenceView<T, V>>;
+/** Fixed-length sequence of given type. */
+export declare const sequenceFixLen: <T, V = T>(type: Descriptor<T, V>, len: number) => Descriptor<T[], SequenceView<T, V>>;
+/** Small dictionary codec. */
+export declare const dictionary: <K, V, V2>(key: Descriptor<K>, value: Descriptor<V, V2>, { sortKeys, fixedLength, }: {
+    sortKeys: (a: K, b: K) => number;
+    fixedLength?: number;
+}) => Descriptor<Map<K, V>, Map<K, V2>>;
+/** Encoding of pair of two values. */
+export declare const pair: <A, AView, B, BView>(a: Descriptor<A, AView>, b: Descriptor<B, BView>) => Descriptor<[A, B], [AView, BView]>;
+/** Custom encoding / decoding logic. */
+export declare const custom: <T>({ name, sizeHint, }: {
+    name: string;
+    sizeHint: SizeHint;
+}, encode: (e: Encoder, x: T) => void, decode: (d: Decoder) => T, skip: (s: Skipper) => void) => Descriptor<T>;
+/**
+ * Descriptor record for union variants.
+ * Each variant can have its own view type, but the union itself won't expose views.
+ */
+type UnionDescriptorRecord<TKind extends number, T extends {
+    kind: TKind;
+}> = {
+    [K in TKind]: Descriptor<Omit<Extract<T, {
+        kind: K;
+    }>, "kind">, unknown>;
+};
+/** Tagged union type encoding. */
+export declare const union: <TKind extends number, T extends {
+    kind: TKind;
+}, TVariants extends UnionDescriptorRecord<TKind, T> = UnionDescriptorRecord<TKind, T>>(name: string, variants: TVariants) => Descriptor<T>;
+/** Choose a descriptor depending on the encoding/decoding context. */
+export declare const select: <T, V = T>({ name, sizeHint, }: {
+    name: string;
+    sizeHint: SizeHint;
+}, chooser: (ctx: unknown | null) => Descriptor<T, V>) => Descriptor<T, V>;
+/**
+ * A descriptor for a more complex POJO.
+ *
+ * This descriptor is very similar to `Class`, but it DOES NOT maintain the
+ * prototype chain of the resulting object - we only care about the shape of
+ * the object here.
+ */
+export declare const object: <T>(descriptors: SimpleDescriptorRecord<T>, name?: string, create?: (o: CodecRecord<T>) => T) => Descriptor<T, ViewOf<T, SimpleDescriptorRecord<T>>>;
+/**
+ * A descriptor for a more complex class type.
+ *
+ * The resulting descriptor is able to encode & decode all of the public fields of
+ * the class, given the map of descriptors for each one of them.
+ *
+ * The resulting decoded object will be an instance of given `Class` unlike simpler,
+ * shape-based `object` method.
+ */
+export declare const Class: <T, D extends DescriptorRecord<T> = DescriptorRecord<T>>(Class: ClassConstructor<T>, descriptors: D) => Descriptor<T, ViewOf<T, D>>;
+/** Typesafe iteration of every descriptor in the record object. */
+export declare function forEachDescriptor<T>(descriptors: DescriptorRecord<T>, f: <K extends keyof DescriptorRecord<T>>(key: K, val: Descriptor<T[K]>) => void): void;
+export {};
+//# sourceMappingURL=descriptors.d.ts.map

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

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

package/packages/core/codec/descriptors.js

@@ -0,0 +1,372 @@
+import { Bytes, BytesBlob } from "#@typeberry/bytes";
+import { tryAsU32 } from "#@typeberry/numbers";
+import { check } from "#@typeberry/utils";
+import { EndOfDataError } from "./decoder.js";
+import { Descriptor, } from "./descriptor.js";
+import { addSizeHints } from "./encoder.js";
+import { Skipper } from "./skip.js";
+import { validateLength } from "./validation.js";
+import { ObjectView, SequenceView } from "./view.js";
+/**
+ * For sequences with unknown length we need to give some size hint.
+ * TODO [ToDr] [opti] This value should be updated when we run some real-data bechmarks.
+ */
+const TYPICAL_SEQUENCE_LENGTH = 64;
+/**
+ * For the size hint for encoding typical dictionaries.
+ * TODO [ToDr] [opti] This value should be updated when we run some real-data bechmarks.
+ */
+export const TYPICAL_DICTIONARY_LENGTH = 32;
+/**
+ * Convert a descriptor for regular array into readonly one.
+ *
+ * NOTE: for performance reasons we assume that every `readonly T[]` is `T[]`,
+ *       and the `readonly` annotation is there just to prevent altering it.
+ *       It's not true in a general case, but should be good enough for us.
+ *
+ */
+export function readonlyArray(desc) {
+    return desc.convert((x) => {
+        check `
+        ${Array.isArray(x)}
+        Non-arrays are not supported as 'readonly': got ${typeof x}, ${x}
+      `;
+        // NOTE [ToDr] This assumption is incorrect in general, but it's documented
+        // in the general note. We avoid `.slice()` the array for performance reasons.
+        return x;
+    }, (x) => x);
+}
+function exactHint(bytes) {
+    return {
+        bytes,
+        isExact: true,
+    };
+}
+/** Fixed-length bytes sequence. */
+export const bytes = (() => {
+    const cache = new Map();
+    return (len) => {
+        let ret = cache.get(len);
+        if (ret === undefined) {
+            ret = Descriptor.new(`Bytes<${len}>`, exactHint(len), (e, v) => e.bytes(v), (d) => d.bytes(len), (s) => s.bytes(len));
+            cache.set(len, ret);
+        }
+        return ret;
+    };
+})();
+/** Zero-size `void` value. */
+export const nothing = Descriptor.new("void", { bytes: 0, isExact: true }, (_e, _v) => { }, (_d) => { }, (_s) => { });
+/** Variable-length U32. */
+export const varU32 = Descriptor.new("var_u32", { bytes: 4, isExact: false }, (e, v) => e.varU32(v), (d) => d.varU32(), (d) => d.varU32());
+/** Variable-length U64. */
+export const varU64 = Descriptor.new("var_u64", { bytes: 8, isExact: false }, (e, v) => e.varU64(v), (d) => d.varU64(), (d) => d.varU64());
+/** Unsigned 64-bit number. */
+export const u64 = Descriptor.withView("u64", exactHint(8), (e, v) => e.i64(v), (d) => d.u64(), (d) => d.u64(), bytes(8));
+/** Unsigned 32-bit number. */
+export const u32 = Descriptor.withView("u32", exactHint(4), (e, v) => e.i32(v), (d) => d.u32(), (d) => d.u32(), bytes(4));
+/** Unsigned 24-bit number. */
+export const u24 = Descriptor.withView("u24", exactHint(3), (e, v) => e.i24(v), (d) => d.u24(), (d) => d.u24(), bytes(3));
+/** Unsigned 16-bit number. */
+export const u16 = Descriptor.withView("u16", exactHint(2), (e, v) => e.i16(v), (d) => d.u16(), (d) => d.u16(), bytes(2));
+/** Unsigned 8-bit number. */
+export const u8 = Descriptor.new("u8", exactHint(1), (e, v) => e.i8(v), (d) => d.u8(), (d) => d.u8());
+/** Signed 64-bit number. */
+export const i64 = Descriptor.withView("i64", exactHint(8), (e, v) => e.i64(v), (d) => d.i64(), (s) => s.u64(), bytes(8));
+/** Signed 32-bit number. */
+export const i32 = Descriptor.withView("i32", exactHint(4), (e, v) => e.i32(v), (d) => d.i32(), (s) => s.u32(), bytes(4));
+/** Signed 24-bit number. */
+export const i24 = Descriptor.withView("i24", exactHint(3), (e, v) => e.i24(v), (d) => d.i24(), (s) => s.u24(), bytes(3));
+/** Signed 16-bit number. */
+export const i16 = Descriptor.withView("i16", exactHint(2), (e, v) => e.i16(v), (d) => d.i16(), (s) => s.u16(), bytes(2));
+/** Signed 8-bit number. */
+export const i8 = Descriptor.new("i8", exactHint(1), (e, v) => e.i8(v), (d) => d.i8(), (s) => s.u8());
+/** 1-byte boolean value. */
+export const bool = Descriptor.new("bool", exactHint(1), (e, v) => e.bool(v), (d) => d.bool(), (s) => s.bool());
+/** Variable-length bytes blob. */
+export const blob = Descriptor.new("BytesBlob", { bytes: TYPICAL_SEQUENCE_LENGTH, isExact: false }, (e, v) => e.bytesBlob(v), (d) => d.bytesBlob(), (s) => s.bytesBlob());
+/** String encoded as variable-length bytes blob. */
+export const string = Descriptor.withView("string", { bytes: TYPICAL_SEQUENCE_LENGTH, isExact: false }, (e, v) => e.bytesBlob(BytesBlob.blobFrom(new TextEncoder().encode(v))), (d) => new TextDecoder("utf8", { fatal: true }).decode(d.bytesBlob().raw), (s) => s.bytesBlob(), blob);
+/** Variable-length bit vector. */
+export const bitVecVarLen = Descriptor.new("BitVec[?]", { bytes: TYPICAL_SEQUENCE_LENGTH >>> 3, isExact: false }, (e, v) => e.bitVecVarLen(v), (d) => d.bitVecVarLen(), (s) => s.bitVecVarLen());
+/** Fixed-length bit vector. */
+export const bitVecFixLen = (bitLen) => Descriptor.new(`BitVec[${bitLen}]`, exactHint(bitLen >>> 3), (e, v) => e.bitVecFixLen(v), (d) => d.bitVecFixLen(bitLen), (s) => s.bitVecFixLen(bitLen));
+/** Optionality wrapper for given type. */
+export const optional = (type) => {
+    const self = Descriptor.new(`Optional<${type.name}>`, addSizeHints({ bytes: 1, isExact: false }, type.sizeHint), (e, v) => e.optional(type, v), (d) => d.optional(type), (s) => s.optional(type));
+    if (hasUniqueView(type)) {
+        return Descriptor.withView(self.name, self.sizeHint, self.encode, self.decode, self.skip, optional(type.View));
+    }
+    return self;
+};
+/** Variable-length sequence of given type. */
+export const sequenceVarLen = (type, options = {
+    minLength: 0,
+    maxLength: 2 ** 32 - 1,
+}) => {
+    const name = `Sequence<${type.name}>[?]`;
+    const typicalLength = options.typicalLength ?? TYPICAL_SEQUENCE_LENGTH;
+    return Descriptor.withView(name, { bytes: typicalLength * type.sizeHint.bytes, isExact: false }, (e, v) => {
+        validateLength(options, v.length, name);
+        e.sequenceVarLen(type, v);
+    }, (d) => {
+        const len = d.varU32();
+        validateLength(options, len, name);
+        return d.sequenceFixLen(type, len);
+    }, (s) => {
+        const len = s.decoder.varU32();
+        validateLength(options, len, name);
+        return s.sequenceFixLen(type, len);
+    }, sequenceViewVarLen(type, options));
+};
+/** Fixed-length sequence of given type. */
+export const sequenceFixLen = (type, len) => Descriptor.withView(`Sequence<${type.name}>[${len}]`, { bytes: len * type.sizeHint.bytes, isExact: type.sizeHint.isExact }, (e, v) => e.sequenceFixLen(type, v), (d) => d.sequenceFixLen(type, len), (s) => s.sequenceFixLen(type, len), sequenceViewFixLen(type, { fixedLength: len }));
+/** Small dictionary codec. */
+export const dictionary = (key, value, { sortKeys, fixedLength, }) => {
+    const self = Descriptor.new(`Dictionary<${key.name}, ${value.name}>[${fixedLength ?? "?"}]`, {
+        bytes: fixedLength !== undefined
+            ? fixedLength * addSizeHints(key.sizeHint, value.sizeHint).bytes
+            : TYPICAL_DICTIONARY_LENGTH * (addSizeHints(key.sizeHint, value.sizeHint).bytes ?? 0),
+        isExact: fixedLength !== undefined ? key.sizeHint.isExact && value.sizeHint.isExact : false,
+    }, (e, v) => {
+        const data = Array.from(v.entries());
+        data.sort((a, b) => sortKeys(a[0], b[0]));
+        // length prefix
+        if (fixedLength === undefined) {
+            e.varU32(tryAsU32(data.length));
+        }
+        for (const [k, v] of data) {
+            key.encode(e, k);
+            value.encode(e, v);
+        }
+    }, (d) => {
+        const map = new Map();
+        const len = fixedLength ?? d.varU32();
+        let prevKey = null;
+        for (let i = 0; i < len; i += 1) {
+            const k = key.decode(d);
+            const v = value.decode(d);
+            if (map.has(k)) {
+                throw new Error(`Duplicate item in the dictionary encoding: "${k}"!`);
+            }
+            if (prevKey !== null && sortKeys(prevKey, k) >= 0) {
+                throw new Error(`The keys in dictionary encoding are not sorted "${prevKey}" >= "${k}"!`);
+            }
+            map.set(k, v);
+            prevKey = k;
+        }
+        return map;
+    }, (s) => {
+        const len = fixedLength ?? s.decoder.varU32();
+        s.sequenceFixLen(key, len);
+        s.sequenceFixLen(value, len);
+    });
+    if (hasUniqueView(value)) {
+        return Descriptor.withView(self.name, self.sizeHint, self.encode, self.decode, self.skip, dictionary(key, value.View, { sortKeys, fixedLength }));
+    }
+    return self;
+};
+/** Encoding of pair of two values. */
+export const pair = (a, b) => {
+    const self = Descriptor.new(`Pair<${a.name}, ${b.name}>`, addSizeHints(a.sizeHint, b.sizeHint), (e, elem) => {
+        a.encode(e, elem[0]);
+        b.encode(e, elem[1]);
+    }, (d) => {
+        const aValue = a.decode(d);
+        const bValue = b.decode(d);
+        return [aValue, bValue];
+    }, (s) => {
+        a.skip(s);
+        b.skip(s);
+    });
+    if (hasUniqueView(a) && hasUniqueView(b)) {
+        return Descriptor.withView(self.name, self.sizeHint, self.encode, self.decode, self.skip, pair(a.View, b.View));
+    }
+    return self;
+};
+/** Custom encoding / decoding logic. */
+export const custom = ({ name, sizeHint = { bytes: 0, isExact: false }, }, encode, decode, skip) => Descriptor.new(name, sizeHint, encode, decode, skip);
+/** Tagged union type encoding. */
+export const union = (name, variants) => {
+    const keys = Object.keys(variants).map(Number);
+    const variantMap = Object.fromEntries(keys.map((key, idx) => [key, idx]));
+    const indexToKey = Object.fromEntries(keys.map((key, idx) => [idx, key]));
+    // Calculate size hint as the minimum variant size + index size
+    const minVariantSize = Math.max(...keys.map((key) => variants[key].sizeHint.bytes));
+    const sizeHint = {
+        bytes: 1 + minVariantSize, // varU32 index + smallest variant
+        isExact: false,
+    };
+    const encode = (e, x) => {
+        const idx = variantMap[x.kind];
+        if (idx === undefined) {
+            throw new Error(`Unknown variant type: ${x.kind} for ${name}`);
+        }
+        e.varU32(tryAsU32(idx));
+        const codec = variants[x.kind];
+        // I'm sorry but I can't figure out a better typing here :)
+        codec.encode(e, x);
+    };
+    const decode = (d) => {
+        const idx = d.varU32();
+        const kind = indexToKey[idx];
+        if (kind === undefined) {
+            throw new Error(`Unknown variant index: ${idx} for ${name}`);
+        }
+        const codec = variants[kind];
+        const value = codec.decode(d);
+        return { kind, ...value };
+    };
+    const skip = (s) => {
+        const idx = s.decoder.varU32();
+        const kind = indexToKey[idx];
+        if (kind === undefined) {
+            throw new Error(`Unknown variant index: ${idx} for ${name}`);
+        }
+        const codec = variants[kind];
+        codec.skip(s);
+    };
+    return Descriptor.new(name, sizeHint, encode, decode, skip);
+};
+/** Choose a descriptor depending on the encoding/decoding context. */
+export const select = ({ name, sizeHint, }, chooser) => {
+    const Self = chooser(null);
+    return Descriptor.withView(name, sizeHint, (e, x) => chooser(e.getContext()).encode(e, x), (d) => chooser(d.getContext()).decode(d), (s) => chooser(s.decoder.getContext()).skip(s), hasUniqueView(Self)
+        ? select({
+            name: Self.View.name,
+            sizeHint: Self.View.sizeHint,
+        }, (ctx) => chooser(ctx).View)
+        : Self.View);
+};
+/**
+ * A descriptor for a more complex POJO.
+ *
+ * This descriptor is very similar to `Class`, but it DOES NOT maintain the
+ * prototype chain of the resulting object - we only care about the shape of
+ * the object here.
+ */
+export const object = (descriptors, name = "object", create = (o) => o) => {
+    return Class({ name, create }, descriptors);
+};
+/**
+ * A descriptor for a more complex class type.
+ *
+ * The resulting descriptor is able to encode & decode all of the public fields of
+ * the class, given the map of descriptors for each one of them.
+ *
+ * The resulting decoded object will be an instance of given `Class` unlike simpler,
+ * shape-based `object` method.
+ */
+export const Class = (Class, descriptors) => {
+    // Calculate a size hint for this class.
+    let sizeHint = exactHint(0);
+    forEachDescriptor(descriptors, (_k, val) => {
+        sizeHint = addSizeHints(sizeHint, val.sizeHint);
+    });
+    const skipper = (s) => {
+        // optimized case for fixed size complex values.
+        if (sizeHint.isExact) {
+            return s.decoder.skip(sizeHint.bytes);
+        }
+        forEachDescriptor(descriptors, (_key, descriptor) => {
+            descriptor.skip(s);
+        });
+    };
+    const view = objectView(Class, descriptors, sizeHint, skipper);
+    // and create the descriptor for the entire class.
+    return Descriptor.withView(Class.name, sizeHint, (e, t) => {
+        forEachDescriptor(descriptors, (key, descriptor) => {
+            const value = t[key];
+            descriptor.encode(e, value);
+        });
+    }, (d) => {
+        const constructorParams = {};
+        forEachDescriptor(descriptors, (key, descriptor) => {
+            const value = descriptor.decode(d);
+            constructorParams[key] = value;
+        });
+        return Class.create(constructorParams);
+    }, skipper, view);
+};
+/** Typesafe iteration of every descriptor in the record object. */
+export function forEachDescriptor(descriptors, f) {
+    for (const key in descriptors) {
+        if (typeof key === "string" && key in descriptors) {
+            const k = key;
+            try {
+                f(k, descriptors[k]);
+            }
+            catch (e) {
+                if (e instanceof EndOfDataError) {
+                    throw new EndOfDataError(`${key}: ${e}`);
+                }
+                throw new Error(`${key}: ${e}`);
+            }
+        }
+    }
+}
+/** A utility function to break an infinite recursion when resolving View types. */
+function hasUniqueView(a) {
+    return a.View !== a;
+}
+function objectView(Class, descriptors, sizeHint, skipper) {
+    // Create a View, based on the `AbstractView`.
+    class ClassView extends ObjectView {
+        constructor(d) {
+            super(d, Class, descriptors);
+        }
+    }
+    // We need to dynamically extend the prototype to add these extra lazy getters.
+    forEachDescriptor(descriptors, (key) => {
+        if (typeof key === "string") {
+            // add method that returns a nested view.
+            Object.defineProperty(ClassView.prototype, key, {
+                get: function () {
+                    return this.get(key);
+                },
+            });
+        }
+    });
+    return Descriptor.new(`View<${Class.name}>`, sizeHint, (e, t) => {
+        const encoded = t.encoded();
+        e.bytes(Bytes.fromBlob(encoded.raw, encoded.length));
+    }, (d) => {
+        const view = new ClassView(d.clone());
+        skipper(new Skipper(d));
+        return view;
+    }, skipper);
+}
+function sequenceViewVarLen(type, options) {
+    const typeBytes = type.sizeHint.bytes;
+    const sizeHint = { bytes: typeBytes * TYPICAL_SEQUENCE_LENGTH, isExact: false };
+    const view = type.name !== type.View.name ? `, ${type.View.name}` : "";
+    const name = `SeqView<${type.name}${view}>[?]`;
+    const skipper = (s) => {
+        const length = s.decoder.varU32();
+        validateLength(options, length, name);
+        return s.sequenceFixLen(type, length);
+    };
+    return Descriptor.new(name, sizeHint, (e, t) => {
+        validateLength(options, t.length, name);
+        const encoded = t.encoded();
+        e.bytes(Bytes.fromBlob(encoded.raw, encoded.length));
+    }, (d) => {
+        const view = new SequenceView(d.clone(), type);
+        skipper(new Skipper(d));
+        return view;
+    }, skipper);
+}
+function sequenceViewFixLen(type, { fixedLength }) {
+    const typeBytes = type.sizeHint.bytes;
+    const sizeHint = { bytes: typeBytes * fixedLength, isExact: type.sizeHint.isExact };
+    const skipper = (s) => s.sequenceFixLen(type, fixedLength);
+    const view = type.name !== type.View.name ? `, ${type.View.name}` : "";
+    const name = `SeqView<${type.name}${view}>[${fixedLength}]`;
+    return Descriptor.new(name, sizeHint, (e, t) => {
+        const encoded = t.encoded();
+        e.bytes(Bytes.fromBlob(encoded.raw, encoded.length));
+    }, (d) => {
+        const view = new SequenceView(d.clone(), type, fixedLength);
+        skipper(new Skipper(d));
+        return view;
+    }, skipper);
+}

package/packages/core/codec/descriptors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=descriptors.test.d.ts.map

package/packages/core/codec/descriptors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptors.test.d.ts","sourceRoot":"","sources":["../../../../../packages/core/codec/descriptors.test.ts"],"names":[],"mappings":""}