@pezkuwi/types-codec 16.5.6 → 16.5.8

package/src/base/Vec.spec.ts

@@ -0,0 +1,224 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import type { PropIndex } from '@pezkuwi/types/interfaces/democracy';
+import type { Codec, CodecTo, ITuple } from '@pezkuwi/types-codec/types';
+
+import { createTypeUnsafe, GenericAccountId as AccountId, Metadata, TypeRegistry } from '@pezkuwi/types';
+import { Text, u32, Vec } from '@pezkuwi/types-codec';
+import rpcMetadata from '@pezkuwi/types-support/metadata/static-bizinikiwi';
+import { decodeAddress, randomAsU8a } from '@pezkuwi/util-crypto';
+
+import { perf } from '../test/performance.js';
+
+const registry = new TypeRegistry();
+const metadata = new Metadata(registry, rpcMetadata);
+const VecU32 = Vec.with(u32);
+
+registry.setMetadata(metadata);
+
+describe('Vec', (): void => {
+  let vector: Vec<Codec>;
+
+  beforeEach((): void => {
+    vector = new Vec(registry, Text, ['1', '23', '345', '4567', new Text(registry, '56789')]);
+  });
+
+  describe('constructor', (): void => {
+    it('fails construction on non-Array, non-Hex inputs', (): void => {
+      // @ts-expect-error We are intentionally passing a non-valid input
+      expect(() => new Vec(registry, Text, '12345')).toThrow(/decoding, found string/);
+      // @ts-expect-error We are intentionally passing a non-valid input
+      expect(() => new Vec(registry, Text, {})).toThrow(/decoding, found object/);
+    });
+
+    it('allows construction via hex & null values', (): void => {
+      // @ts-expect-error We are intentionally passing a non-valid input
+      expect(new Vec(registry, Text, null)).toHaveLength(0);
+    });
+
+    it('decodes a complex type via construction (1)', (): void => {
+      const test = createTypeUnsafe<Vec<ITuple<[PropIndex, AccountId]>>>(registry, 'Vec<(PropIndex, AccountId)>', [new Uint8Array([
+        4, 10, 0, 0, 0, 209, 114, 167, 76, 218, 76, 134, 89, 18, 195, 43, 160, 168, 10, 87, 174, 105, 171, 174, 65, 14, 92, 203, 89, 222, 232, 78, 47, 68, 50, 219, 79
+      ])]);
+
+      expect(test[0][0].toNumber()).toEqual(10);
+      expect(test[0][1].toString()).toEqual('5GoKvZWG5ZPYL1WUovuHW3zJBWBP5eT8CbqjdRY4Q6iMaQua');
+    });
+
+    it('decodes a complex type via construction (2)', (): void => {
+      const INPUT = '0x08cc0200000000ce0200000001';
+      const test = createTypeUnsafe<Vec<Codec>>(registry, 'Vec<(u32, [u32; 0], u16)>', [INPUT]);
+
+      expect(test).toHaveLength(2);
+      expect(test.toHex()).toEqual(INPUT);
+    });
+
+    it('allows construction via JSON', (): void => {
+      expect(
+        new Vec(registry, Text, ['6', '7']).toJSON()
+      ).toEqual(['6', '7']);
+    });
+
+    it('allows construction via JSON (string type)', (): void => {
+      expect(
+        new Vec(registry, 'u32', ['6', '7']).toJSON()
+      ).toEqual([6, 7]);
+    });
+
+    it('decodes reusing instantiated inputs', (): void => {
+      const foo = new Text(registry, 'bar');
+
+      expect(
+        (new Vec(registry, Text, [foo]))[0]
+      ).toBe(foo);
+    });
+  });
+
+  describe('vector-like functions', (): void => {
+    it('wraps a sequence of values', (): void => {
+      expect(vector).toHaveLength(5);
+    });
+
+    it('has a sane representation for toString', (): void => {
+      expect(vector.toString()).toEqual('[1, 23, 345, 4567, 56789]');
+    });
+
+    it('encodes with length prefix on toU8a()', (): void => {
+      expect(vector.toU8a()).toEqual(new Uint8Array([
+        5 << 2,
+        1 << 2, 49,
+        2 << 2, 50, 51,
+        3 << 2, 51, 52, 53,
+        4 << 2, 52, 53, 54, 55,
+        5 << 2, 53, 54, 55, 56, 57
+      ]));
+    });
+
+    it('encodes without length prefix on toU8a(true)', (): void => {
+      expect(vector.toU8a(true)).toEqual(new Uint8Array([
+        1 << 2, 49,
+        2 << 2, 50, 51,
+        3 << 2, 51, 52, 53,
+        4 << 2, 52, 53, 54, 55,
+        5 << 2, 53, 54, 55, 56, 57
+      ]));
+    });
+
+    it('exposes the type', (): void => {
+      expect(vector.Type).toEqual('Text');
+    });
+
+    it('allows retrieval of a specific item', (): void => {
+      expect(
+        vector[2].toString()
+      ).toEqual('345');
+    });
+
+    it('exposes a working forEach', (): void => {
+      const result: Record<number, string> = {};
+
+      vector.forEach((e, i): void => {
+        result[i] = e.toString();
+      });
+
+      expect(result).toEqual({
+        0: '1',
+        1: '23',
+        2: '345',
+        3: '4567',
+        4: '56789'
+      });
+    });
+
+    it('exposes a working concat', (): void => {
+      expect(
+        vector.concat(new Vec(registry, Text, ['987', '654'])).toString()
+      ).toEqual('1,23,345,4567,56789,987,654');
+    });
+
+    it('exposes a working filter', (): void => {
+      expect(
+        vector.filter((_, i): boolean => i >= 3).toString()
+      ).toEqual('4567,56789');
+    });
+
+    it('exposes a working map', (): void => {
+      expect(
+        vector.map((e): string => e.toString().substring(0, 1))
+      ).toEqual(['1', '2', '3', '4', '5']);
+    });
+
+    it('exposes a working reduce', (): void => {
+      expect(
+        vector.reduce((r, e): string => `${r}${e.toString()}`, '')
+      ).toEqual('123345456756789');
+    });
+
+    it('exposes a working indexOf', (): void => {
+      expect(vector.indexOf('1')).toEqual(0);
+      expect(vector.indexOf(new Text(registry, '23'))).toEqual(1);
+      expect(vector.indexOf('0')).toEqual(-1);
+    });
+  });
+
+  describe('encode', (): void => {
+    const testEncode = (to: CodecTo, expected: any): void =>
+      it(`can encode ${to}`, (): void => {
+        expect(vector[to]()).toEqual(expected);
+      });
+
+    testEncode('toHex', '0x1404310832330c3334351034353637143536373839');
+    testEncode('toJSON', ['1', '23', '345', '4567', '56789']);
+    testEncode('toString', '[1, 23, 345, 4567, 56789]');
+    testEncode('toU8a', Uint8Array.from([20, 4, 49, 8, 50, 51, 12, 51, 52, 53, 16, 52, 53, 54, 55, 20, 53, 54, 55, 56, 57]));
+  });
+
+  describe('utils', (): void => {
+    const vec = new Vec(registry, Text, ['123', '456']);
+
+    it('compares against codec types', (): void => {
+      expect(vec.eq([new Text(registry, '123'), new Text(registry, '456')])).toBe(true);
+    });
+
+    it('compares against codec + primitive types', (): void => {
+      expect(vec.eq(['123', new Text(registry, '456')])).toBe(true);
+    });
+
+    it('finds the index of an value', (): void => {
+      const myId = '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY';
+      const vec = new Vec(registry, AccountId, [
+        '5HGjWAeFDfFCWPsjFQdVV2Msvz2XtMktvgocEZcCj68kUMaw', '5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty', '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY'
+      ]);
+
+      expect(vec.indexOf(myId)).toEqual(2);
+    });
+
+    it('allows a slice operator', (): void => {
+      const vec = registry.createType('Vec<AccountId>', [
+        randomAsU8a(), randomAsU8a(), randomAsU8a(), randomAsU8a(), randomAsU8a(), randomAsU8a(), randomAsU8a(), randomAsU8a(), randomAsU8a(), randomAsU8a()
+      ]);
+
+      expect(vec).toHaveLength(10);
+      expect(vec.slice(2, 7)).toHaveLength(5);
+    });
+
+    it('has a sane inspect', (): void => {
+      const addrs = [
+        '5HGjWAeFDfFCWPsjFQdVV2Msvz2XtMktvgocEZcCj68kUMaw', '5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty', '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY'
+      ];
+      const vec = registry.createType('Vec<AccountId>', addrs);
+
+      expect(vec.inspect()).toEqual({
+        inner: addrs.map((a) => ({
+          outer: [decodeAddress(a)]
+        })),
+        outer: [new Uint8Array([3 << 2])]
+      });
+    });
+  });
+
+  perf('Vec<U32>', 40_000, [[new Uint8Array([3 << 2, 11, 12, 13, 14, 21, 22, 23, 24, 31, 32, 33, 34])]], (v: Uint8Array) => new VecU32(registry, v));
+});

package/src/base/Vec.ts

@@ -0,0 +1,133 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '@pezkuwi/util/types';
+import type { Codec, CodecClass, DefinitionSetter, Registry } from '../types/index.js';
+
+import { compactFromU8aLim, identity, isHex, isU8a, logger, stringify, u8aToU8a } from '@pezkuwi/util';
+
+import { AbstractArray } from '../abstract/Array.js';
+import { decodeU8aVec, typeToConstructor } from '../utils/index.js';
+
+const MAX_LENGTH = 512 * 1024;
+
+const l = logger('Vec');
+
+function decodeVecLength (value: Uint8Array | HexString | unknown[]): [Uint8Array | unknown[] | null, number, number] {
+  if (Array.isArray(value)) {
+    return [value, value.length, 0];
+  } else if (isU8a(value) || isHex(value)) {
+    const u8a = u8aToU8a(value);
+    const [startAt, length] = compactFromU8aLim(u8a);
+
+    if (length > MAX_LENGTH) {
+      throw new Error(`Vec length ${length.toString()} exceeds ${MAX_LENGTH}`);
+    }
+
+    return [u8a, length, startAt];
+  } else if (!value) {
+    return [null, 0, 0];
+  }
+
+  throw new Error(`Expected array/hex input to Vec<*> decoding, found ${typeof value}: ${stringify(value)}`);
+}
+
+export function decodeVec<T extends Codec> (registry: Registry, result: T[], value: Uint8Array | HexString | unknown[] | null, startAt: number, Type: CodecClass<T>): [number, number] {
+  if (Array.isArray(value)) {
+    const count = result.length;
+
+    for (let i = 0; i < count; i++) {
+      // 26/08/2022 this is actually a false positive - after recent eslint upgdates
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const entry = value[i];
+
+      try {
+        result[i] = entry instanceof Type
+          ? entry
+          : new Type(registry, entry);
+      } catch (error) {
+        l.error(`Unable to decode on index ${i}`, (error as Error).message);
+
+        throw error;
+      }
+    }
+
+    return [0, 0];
+  } else if (!value) {
+    return [0, 0];
+  }
+
+  // we don't need more checks, we already limited it via the length decoding
+  return decodeU8aVec(registry, result, u8aToU8a(value), startAt, Type);
+}
+
+/**
+ * @name Vec
+ * @description
+ * This manages codec arrays. Internally it keeps track of the length (as decoded) and allows
+ * construction with the passed `Type` in the constructor. It is an extension to Array, providing
+ * specific encoding/decoding on top of the base type.
+ */
+export class Vec<T extends Codec> extends AbstractArray<T> {
+  #Type: CodecClass<T>;
+
+  constructor (registry: Registry, Type: CodecClass<T> | string, value: Uint8Array | HexString | unknown[] = [], { definition, setDefinition = identity }: DefinitionSetter<CodecClass<T>> = {}) {
+    const [decodeFrom, length, startAt] = decodeVecLength(value);
+
+    super(registry, length);
+
+    this.#Type = definition || setDefinition(typeToConstructor<T>(registry, Type));
+
+    this.initialU8aLength = (
+      isU8a(decodeFrom)
+        ? decodeU8aVec(registry, this, decodeFrom, startAt, this.#Type)
+        : decodeVec(registry, this, decodeFrom, startAt, this.#Type)
+    )[0];
+  }
+
+  public static with<O extends Codec> (Type: CodecClass<O> | string): CodecClass<Vec<O>> {
+    let definition: CodecClass<O> | undefined;
+
+    // eslint-disable-next-line no-return-assign
+    const setDefinition = <T> (d: CodecClass<T>) =>
+      (definition = d as unknown as CodecClass<O>) as unknown as CodecClass<T>;
+
+    return class extends Vec<O> {
+      constructor (registry: Registry, value?: any[]) {
+        super(registry, Type, value, { definition, setDefinition });
+      }
+    };
+  }
+
+  /**
+   * @description The type for the items
+   */
+  public get Type (): string {
+    return this.#Type.name;
+  }
+
+  /**
+   * @description Finds the index of the value in the array
+   */
+  public override indexOf (other?: unknown): number {
+    // convert type first, this removes overhead from the eq
+    const check = other instanceof this.#Type
+      ? other
+      : new this.#Type(this.registry, other);
+
+    for (let i = 0, count = this.length; i < count; i++) {
+      if (check.eq(this[i])) {
+        return i;
+      }
+    }
+
+    return -1;
+  }
+
+  /**
+   * @description Returns the base runtime type name for this instance
+   */
+  public toRawType (): string {
+    return `Vec<${this.registry.getClassName(this.#Type) || new this.#Type(this.registry).toRawType()}>`;
+  }
+}

package/src/base/VecAny.ts

@@ -0,0 +1,23 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Codec } from '../types/index.js';
+
+import { AbstractArray } from '../abstract/Array.js';
+
+/**
+ * @name VecAny
+ * @description
+ * This manages codec arrays, assuming that the inputs are already of type Codec. Unlike
+ * a vector, this can be used to manage array-like structures with variable arguments of
+ * any types
+ */
+export class VecAny<T extends Codec> extends AbstractArray<T> {
+  /**
+   * @description Returns the base runtime type name for this instance
+   */
+  public toRawType (): string {
+    // FIXME This is basically an any type, cannot instantiate via createType
+    return 'Vec<Codec>';
+  }
+}

package/src/base/VecFixed.spec.ts

@@ -0,0 +1,78 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { TypeRegistry } from '@pezkuwi/types';
+import { Text, u16, VecFixed } from '@pezkuwi/types-codec';
+import { stringToU8a } from '@pezkuwi/util';
+
+describe('VecFixed', (): void => {
+  const registry = new TypeRegistry();
+
+  describe('construction', (): void => {
+    it('constructs via empty', (): void => {
+      expect(new VecFixed(registry, Text, 2).toHex()).toEqual('0x0000');
+    });
+
+    it('constructs via Uint8Array', (): void => {
+      expect(new VecFixed(registry, Text, 2, new Uint8Array([0x00, 0x04, 0x31])).toHex()).toEqual('0x000431');
+    });
+
+    it('constructs via hex', (): void => {
+      expect(new VecFixed(registry, u16, 2, '0x12345678').toHex()).toEqual('0x12345678');
+    });
+
+    it('decodes reusing instance inputs', (): void => {
+      const foo = new Text(registry, 'bar');
+
+      expect(
+        (new VecFixed(registry, Text, 1, [foo]))[0]
+      ).toBe(foo);
+    });
+  });
+
+  describe('utils', (): void => {
+    let test: VecFixed<Text>;
+
+    beforeEach((): void => {
+      test = new (VecFixed.with(Text, 5))(registry, ['1', '2', '3', undefined, '56']);
+    });
+
+    it('has a sane string types', (): void => {
+      expect(test.toRawType()).toEqual('[Text;5]');
+      expect(test.Type).toEqual('Text');
+    });
+
+    it('has a correct toHex', (): void => {
+      // each entry length 1 << 2, char as hex (0x31 === `1`), one empty
+      expect(test.toHex()).toEqual('0x04310432043300083536');
+    });
+
+    it('has empty Uint8Array when length is 0', (): void => {
+      const test = new (VecFixed.with(Text, 0))(registry);
+
+      expect(test.encodedLength).toEqual(0);
+      expect(test.toU8a()).toEqual(new Uint8Array([]));
+    });
+
+    it('has equivalent to 1 Uint8Array when length is 1', (): void => {
+      const test = new (VecFixed.with(Text, 1))(registry, ['hello']);
+
+      expect(test.encodedLength).toEqual(1 + 5);
+      expect(test.toU8a()).toEqual(new Uint8Array([20, 104, 101, 108, 108, 111]));
+    });
+
+    it('has a sane inspect', (): void => {
+      expect(test.inspect()).toEqual({
+        inner: [
+          { outer: [new Uint8Array([1 << 2]), stringToU8a('1')] },
+          { outer: [new Uint8Array([1 << 2]), stringToU8a('2')] },
+          { outer: [new Uint8Array([1 << 2]), stringToU8a('3')] },
+          { outer: [new Uint8Array([0])] },
+          { outer: [new Uint8Array([2 << 2]), stringToU8a('56')] }
+        ]
+      });
+    });
+  });
+});

package/src/base/VecFixed.ts

@@ -0,0 +1,92 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '@pezkuwi/util/types';
+import type { Codec, CodecClass, DefinitionSetter, Inspect, Registry } from '../types/index.js';
+
+import { identity, isU8a, u8aConcatStrict } from '@pezkuwi/util';
+
+import { AbstractArray } from '../abstract/Array.js';
+import { decodeU8aVec, typeToConstructor } from '../utils/index.js';
+import { decodeVec } from './Vec.js';
+
+/**
+ * @name VecFixed
+ * @description
+ * This manages codec arrays of a fixed length
+ */
+export class VecFixed<T extends Codec> extends AbstractArray<T> {
+  #Type: CodecClass<T>;
+
+  constructor (registry: Registry, Type: CodecClass<T> | string, length: number, value: Uint8Array | HexString | unknown[] = [] as unknown[], { definition, setDefinition = identity }: DefinitionSetter<CodecClass<T>> = {}) {
+    super(registry, length);
+
+    this.#Type = definition || setDefinition(typeToConstructor<T>(registry, Type));
+
+    this.initialU8aLength = (
+      isU8a(value)
+        ? decodeU8aVec(registry, this, value, 0, this.#Type)
+        : decodeVec(registry, this, value, 0, this.#Type)
+    )[1];
+  }
+
+  public static with<O extends Codec> (Type: CodecClass<O> | string, length: number): CodecClass<VecFixed<O>> {
+    let definition: CodecClass<O> | undefined;
+
+    // eslint-disable-next-line no-return-assign
+    const setDefinition = <T> (d: CodecClass<T>) =>
+      (definition = d as unknown as CodecClass<O>) as unknown as CodecClass<T>;
+
+    return class extends VecFixed<O> {
+      constructor (registry: Registry, value?: any[]) {
+        super(registry, Type, length, value, { definition, setDefinition });
+      }
+    };
+  }
+
+  /**
+   * @description The type for the items
+   */
+  public get Type (): string {
+    return new this.#Type(this.registry).toRawType();
+  }
+
+  /**
+   * @description The length of the value when encoded as a Uint8Array
+   */
+  public override get encodedLength (): number {
+    let total = 0;
+
+    for (let i = 0, count = this.length; i < count; i++) {
+      total += this[i].encodedLength;
+    }
+
+    return total;
+  }
+
+  /**
+   * @description Returns a breakdown of the hex encoding for this Codec
+   */
+  public override inspect (): Inspect {
+    return {
+      inner: this.inspectInner()
+    };
+  }
+
+  public override toU8a (): Uint8Array {
+    // we override, we don't add the length prefix for ourselves, and at the same time we
+    // ignore isBare on entries, since they should be properly encoded at all times
+    const encoded = this.toU8aInner();
+
+    return encoded.length
+      ? u8aConcatStrict(encoded)
+      : new Uint8Array([]);
+  }
+
+  /**
+   * @description Returns the base runtime type name for this instance
+   */
+  public toRawType (): string {
+    return `[${this.Type};${this.length}]`;
+  }
+}

package/src/base/index.ts

@@ -0,0 +1,15 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export { Compact } from './Compact.js';
+export { DoNotConstruct } from './DoNotConstruct.js';
+export { Enum } from './Enum.js';
+export { Int } from './Int.js';
+export { Null } from './Null.js';
+export { Option } from './Option.js';
+export { Result } from './Result.js';
+export { Tuple } from './Tuple.js';
+export { UInt } from './UInt.js';
+export { Vec } from './Vec.js';
+export { VecAny } from './VecAny.js';
+export { VecFixed } from './VecFixed.js';

package/src/bundle.ts

@@ -0,0 +1,13 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// all named
+export { packageInfo } from './packageInfo.js';
+
+// all starred
+export * from './abstract/index.js';
+export * from './base/index.js';
+export * from './extended/index.js';
+export * from './native/index.js';
+export * from './primitive/index.js';
+export * from './utils/index.js';

package/src/checkTypes.manual.ts

@@ -0,0 +1,12 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import '@pezkuwi/types-augment';
+
+import { TypeRegistry } from '@pezkuwi/types';
+
+import { U32 } from './index.js';
+
+const registry = new TypeRegistry();
+
+console.log(new U32(registry).divn(1));