@pezkuwi/types-codec 16.5.17 → 16.5.19

package/src/base/Result.ts

@@ -0,0 +1,79 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Codec, CodecClass, IResult, Registry } from '../types/index.js';
+
+import { Enum } from './Enum.js';
+
+/**
+ * @name Result
+ * @description
+ * A Result maps to the Rust Result type, that can either wrap a success or error value
+ */
+export class Result<O extends Codec, E extends Codec> extends Enum implements IResult<O, E> {
+  constructor (registry: Registry, Ok: CodecClass<O> | string, Err: CodecClass<E> | string, value?: unknown) {
+    // NOTE This is order-dependent, Ok (with index 0) needs to be first
+    // eslint-disable-next-line sort-keys
+    super(registry, { Ok, Err }, value);
+  }
+
+  public static override with<O extends Codec, E extends Codec> (Types: { Ok: CodecClass<O> | string; Err: CodecClass<E> | string }): CodecClass<Result<O, E>> {
+    return class extends Result<O, E> {
+      constructor (registry: Registry, value?: unknown) {
+        super(registry, Types.Ok, Types.Err, value);
+      }
+    };
+  }
+
+  /**
+   * @description Returns the wrapper Err value (if isErr)
+   */
+  public get asErr (): E {
+    if (!this.isErr) {
+      throw new Error('Cannot extract Err value from Ok result, check isErr first');
+    }
+
+    return this.value as E;
+  }
+
+  /**
+   * @description Returns the wrapper Ok value (if isOk)
+   */
+  public get asOk (): O {
+    if (!this.isOk) {
+      throw new Error('Cannot extract Ok value from Err result, check isOk first');
+    }
+
+    return this.value as O;
+  }
+
+  /**
+   * @description Checks if the Result has no value
+   */
+  public override get isEmpty (): boolean {
+    return this.isOk && this.value.isEmpty;
+  }
+
+  /**
+   * @description Checks if the Result wraps an Err value
+   */
+  public get isErr (): boolean {
+    return !this.isOk;
+  }
+
+  /**
+   * @description Checks if the Result wraps an Ok value
+   */
+  public get isOk (): boolean {
+    return this.index === 0;
+  }
+
+  /**
+   * @description Returns the base runtime type name for this instance
+   */
+  public override toRawType (): string {
+    const Types = this._toRawStruct() as { Ok: unknown; Err: unknown };
+
+    return `Result<${Types.Ok as string},${Types.Err as string}>`;
+  }
+}

package/src/base/Tuple.spec.ts

@@ -0,0 +1,161 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import type { BlockNumber, VoteThreshold } from '@pezkuwi/types/interfaces';
+import type { AnyTupleValue, CodecTo } from '@pezkuwi/types-codec/types';
+
+import { Metadata, TypeRegistry } from '@pezkuwi/types';
+import { Text, Tuple, U32, U128 } from '@pezkuwi/types-codec';
+import rpcMetadata from '@pezkuwi/types-support/metadata/static-bizinikiwi';
+import { stringToU8a } from '@pezkuwi/util';
+
+describe('Tuple', (): void => {
+  const registry = new TypeRegistry();
+  let tuple: Tuple;
+
+  beforeEach((): void => {
+    tuple = new Tuple(
+      registry,
+      [Text, U32],
+      ['bazzing', 69]
+    );
+  });
+
+  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 Tuple(registry, [Text, Text], '12345')).toThrow(/Expected array input to Tuple decoding, found string/);
+      // @ts-expect-error We are intentionally passing a non-valid input
+      expect(() => new Tuple(registry, [Text, Text], {})).toThrow(/Expected array input to Tuple decoding, found object/);
+    });
+  });
+
+  describe('decoding', (): void => {
+    const testDecode = (type: string, input: AnyTupleValue): void =>
+      it(`can decode from ${type}`, (): void => {
+        const t = new Tuple(registry, [
+          Text,
+          U32
+        ], input);
+
+        expect(
+          t.toJSON()
+        ).toEqual(['bazzing', 69]);
+      });
+
+    testDecode('array', ['bazzing', 69]);
+    testDecode('hex', '0x1c62617a7a696e6745000000');
+    testDecode('Uint8Array', Uint8Array.from([28, 98, 97, 122, 122, 105, 110, 103, 69, 0, 0, 0]));
+
+    it('decodes reusing instantiated inputs', (): void => {
+      const foo = new Text(registry, 'bar');
+
+      expect(
+        (new Tuple(registry, [Text], [foo]))[0]
+      ).toBe(foo);
+    });
+
+    it('decodes properly from complex types', (): void => {
+      const INPUT = '0xcc0200000000';
+      const test = registry.createType('(u32, [u32; 0], u16)', INPUT);
+
+      expect(test.encodedLength).toEqual(4 + 0 + 2);
+      expect(test.toHex()).toEqual(INPUT);
+    });
+  });
+
+  describe('encoding', (): void => {
+    const testEncode = (to: CodecTo | 'toArray', expected: any): void =>
+      it(`can encode ${to}`, (): void => {
+        expect(tuple[to]()).toEqual(expected);
+      });
+
+    testEncode('toHex', '0x1c62617a7a696e6745000000');
+    testEncode('toJSON', ['bazzing', 69]);
+    testEncode('toU8a', Uint8Array.from([28, 98, 97, 122, 122, 105, 110, 103, 69, 0, 0, 0]));
+    testEncode('toString', '["bazzing",69]');
+  });
+
+  it('creates from string types', (): void => {
+    expect(
+      new Tuple(
+        registry,
+        ['Text', 'u32', U32],
+        ['foo', 69, 42]
+      ).toString()
+    ).toEqual('["foo",69,42]');
+  });
+
+  it('creates properly via actual hex string', (): void => {
+    const metadata = new Metadata(registry, rpcMetadata);
+
+    registry.setMetadata(metadata);
+
+    const test = new (Tuple.with([
+      registry.createClass('BlockNumber'), registry.createClass('VoteThreshold')
+    ]
+    ))(registry, '0x6219000001');
+
+    expect((test[0] as BlockNumber).toNumber()).toEqual(6498);
+    expect((test[1] as VoteThreshold).toNumber()).toEqual(1);
+  });
+
+  it('exposes the Types', (): void => {
+    expect(tuple.Types).toEqual(['Text', 'u32']);
+  });
+
+  it('exposes the Types (object creation)', (): void => {
+    const test = new Tuple(registry, {
+      BlockNumber: registry.createClass('BlockNumber'),
+      VoteThreshold: registry.createClass('VoteThreshold')
+    }, []);
+
+    expect(test.Types).toEqual(['BlockNumber', 'VoteThreshold']);
+  });
+
+  it('exposes filter', (): void => {
+    expect(tuple.filter((v): boolean => v.toJSON() === 69)).toEqual([new U32(registry, 69)]);
+  });
+
+  it('exposes map', (): void => {
+    expect(tuple.map((v): string => v.toString())).toEqual(['bazzing', '69']);
+  });
+
+  describe('utils', (): void => {
+    it('compares against inputs', (): void => {
+      expect(tuple.eq(['bazzing', 69])).toBe(true);
+    });
+
+    it('compares against inputs (mismatch)', (): void => {
+      expect(tuple.eq(['bazzing', 72])).toBe(false);
+    });
+
+    it('has a sane inspect', (): void => {
+      expect(
+        tuple.inspect()
+      ).toEqual({
+        inner: [
+          { outer: [new Uint8Array([7 << 2]), stringToU8a('bazzing')] },
+          { outer: [new Uint8Array([69, 0, 0, 0])] }
+        ]
+      });
+    });
+  });
+
+  describe('toRawType', (): void => {
+    it('generates sane value with array types', (): void => {
+      expect(
+        new Tuple(registry, [U128, registry.createClass('BlockNumber')]).toRawType()
+      ).toEqual('(u128,BlockNumber)');
+    });
+
+    it('generates sane value with object types', (): void => {
+      expect(
+        // eslint-disable-next-line sort-keys
+        new Tuple(registry, { number: U128, blockNumber: registry.createClass('BlockNumber') }).toRawType()
+      ).toEqual('(u128,BlockNumber)');
+    });
+  });
+});

package/src/base/Tuple.ts

@@ -0,0 +1,149 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AnyTupleValue, Codec, CodecClass, DefinitionSetter, Inspect, ITuple, Registry } from '../types/index.js';
+
+import { identity, isFunction, isHex, isString, isU8a, stringify, u8aConcatStrict, u8aToU8a } from '@pezkuwi/util';
+
+import { AbstractArray } from '../abstract/Array.js';
+import { decodeU8a, mapToTypeMap, typesToConstructors, typeToConstructor } from '../utils/index.js';
+
+type TupleType = (CodecClass | string);
+
+type TupleTypes = TupleType[] | Record<string, CodecClass | string>;
+
+type Definition = [CodecClass[], string[]];
+
+/** @internal */
+function decodeTuple (registry: Registry, result: Codec[], value: Exclude<AnyTupleValue, Uint8Array> | undefined, Classes: Definition): [Codec[], number] {
+  if (Array.isArray(value)) {
+    const Types = Classes[0];
+
+    for (let i = 0, count = Types.length; i < count; i++) {
+      try {
+        const entry = value?.[i];
+
+        result[i] = entry instanceof Types[i]
+          ? entry
+          : new Types[i](registry, entry);
+      } catch (error) {
+        throw new Error(`Tuple: failed on ${i}:: ${(error as Error).message}`);
+      }
+    }
+
+    return [result, 0];
+  } else if (isHex(value)) {
+    return decodeU8a(registry, result, u8aToU8a(value), Classes);
+  } else if (!value || !result.length) {
+    const Types = Classes[0];
+
+    for (let i = 0, count = Types.length; i < count; i++) {
+      result[i] = new Types[i](registry);
+    }
+
+    return [result, 0];
+  }
+
+  throw new Error(`Expected array input to Tuple decoding, found ${typeof value}: ${stringify(value)}`);
+}
+
+/**
+ * @name Tuple
+ * @description
+ * A Tuple defines an anonymous fixed-length array, where each element has its
+ * own type. It extends the base JS `Array` object.
+ */
+export class Tuple extends AbstractArray<Codec> implements ITuple<Codec[]> {
+  #Types: Definition;
+
+  constructor (registry: Registry, Types: TupleTypes | TupleType, value?: AnyTupleValue, { definition, setDefinition = identity }: DefinitionSetter<Definition> = {}) {
+    const Classes = definition || setDefinition(
+      Array.isArray(Types)
+        ? [typesToConstructors(registry, Types), []]
+        : isFunction(Types) || isString(Types)
+          ? [[typeToConstructor(registry, Types)], []]
+          : mapToTypeMap(registry, Types)
+    );
+
+    super(registry, Classes[0].length);
+
+    this.initialU8aLength = (
+      isU8a(value)
+        ? decodeU8a(registry, this, value, Classes)
+        : decodeTuple(registry, this, value, Classes)
+    )[1];
+    this.#Types = Classes;
+  }
+
+  public static with (Types: TupleTypes | TupleType): CodecClass<Tuple> {
+    let definition: Definition | undefined;
+
+    // eslint-disable-next-line no-return-assign
+    const setDefinition = (d: Definition) =>
+      definition = d;
+
+    return class extends Tuple {
+      constructor (registry: Registry, value?: AnyTupleValue) {
+        super(registry, Types, value, { definition, setDefinition });
+      }
+    };
+  }
+
+  /**
+   * @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 The types definition of the tuple
+   */
+  public get Types (): string[] {
+    return this.#Types[1].length
+      ? this.#Types[1]
+      : this.#Types[0].map((T) => new T(this.registry).toRawType());
+  }
+
+  /**
+   * @description Returns a breakdown of the hex encoding for this Codec
+   */
+  public override inspect (): Inspect {
+    return {
+      inner: this.inspectInner()
+    };
+  }
+
+  /**
+   * @description Returns the base runtime type name for this instance
+   */
+  public toRawType (): string {
+    const types = this.#Types[0].map((T) =>
+      this.registry.getClassName(T) || new T(this.registry).toRawType()
+    );
+
+    return `(${types.join(',')})`;
+  }
+
+  /**
+   * @description Returns the string representation of the value
+   */
+  public override toString (): string {
+    // Overwrite the default toString representation of Array.
+    return stringify(this.toJSON());
+  }
+
+  /**
+   * @description Encodes the value as a Uint8Array as per the SCALE specifications
+   * @param isBare true when the value has none of the type-specific prefixes (internal)
+   */
+  public override toU8a (isBare?: boolean): Uint8Array {
+    return u8aConcatStrict(this.toU8aInner(isBare));
+  }
+}

package/src/base/UInt.spec.ts

@@ -0,0 +1,192 @@
+// 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 { UInt } from '@pezkuwi/types-codec';
+import { BN, BN_TWO, isBn } from '@pezkuwi/util';
+
+import { perf } from '../test/performance.js';
+
+describe('UInt', (): void => {
+  const registry = new TypeRegistry();
+
+  it('fails on > MAX_SAFE_INTEGER and float', (): void => {
+    // eslint-disable-next-line @typescript-eslint/no-loss-of-precision, no-loss-of-precision
+    expect(() => new UInt(registry, 9007199254740999)).toThrow(/integer <= Number.MAX_SAFE_INTEGER/);
+    // eslint-disable-next-line @typescript-eslint/no-loss-of-precision, no-loss-of-precision
+    expect(() => new UInt(registry, -9007199254740999)).toThrow(/integer <= Number.MAX_SAFE_INTEGER/);
+    expect(() => new UInt(registry, 9.123)).toThrow(/integer <= Number.MAX_SAFE_INTEGER/);
+  });
+
+  it('fails on strings with decimal points & scientific notation', (): void => {
+    expect(() => new UInt(registry, '123.4')).toThrow(/not contain decimal points/);
+    expect(() => new UInt(registry, '9e10')).toThrow(/not contain decimal points/);
+  });
+
+  it('decodes an empty Uint8array correctly', (): void => {
+    expect(
+      new UInt(registry, new Uint8Array()).toNumber()
+    ).toEqual(0);
+  });
+
+  it('still has the BN interfaces', (): void => {
+    expect([
+      new UInt(registry, 32).mul(BN_TWO).toNumber(),
+      new UInt(registry, 64).divn(2).toNumber()
+    ]).toEqual([64, 32]);
+  });
+
+  it('is a BN instance', (): void => {
+    const test = new UInt(registry, 16);
+
+    expect(isBn(test)).toBe(true);
+    expect(BN.isBN(test)).toBe(true);
+    expect(test instanceof BN).toBe(true);
+  });
+
+  // e.g. headers
+  it('decodes hex that are not multiples of 2', (): void => {
+    expect(new UInt(registry, '0x123').toNumber()).toEqual(0x123);
+    expect(new UInt(registry, '0x0123').toNumber()).toEqual(0x123);
+  });
+
+  it('fails on a number that is too large for the bits specified', (): void => {
+    expect(
+      (): UInt => new UInt(registry, '12345678901234567890123456789012345678901234567890', 32)
+    ).toThrow('u32: Input too large. Found input with 164 bits, expected 32');
+  });
+
+  it('fails on negative numbers', (): void => {
+    expect(
+      (): UInt => new UInt(registry, -123, 32)
+    ).toThrow('u32: Negative number passed to unsigned type');
+  });
+
+  it('allows for construction via BigInt', (): void => {
+    expect(
+      new UInt(registry, 123456789123456789123456789n, 128).toHuman()
+    ).toEqual('123,456,789,123,456,789,123,456,789');
+  });
+
+  it('converts to Little Endian from the provided value', (): void => {
+    expect(
+      new UInt(registry, 1234567).toU8a()
+    ).toEqual(new Uint8Array([135, 214, 18, 0, 0, 0, 0, 0]));
+  });
+
+  it('converts to Little Endian from the provided value (bitLength)', (): void => {
+    expect(
+      new UInt(registry, 1234567, 32).toU8a()
+    ).toEqual(new Uint8Array([135, 214, 18, 0]));
+  });
+
+  it('converts to hex/string', (): void => {
+    const u = new UInt(registry, '0x12', 16);
+
+    expect(u.toHex()).toEqual('0x0012');
+    expect(u.toString()).toEqual('18');
+  });
+
+  it('converts to equivalents', (): void => {
+    const a = new UInt(registry, '123');
+
+    expect(
+      new UInt(registry, a).toNumber()
+    ).toEqual(123);
+  });
+
+  it('converts to JSON representation based on size', (): void => {
+    expect(new UInt(registry, '0x12345678', 32).toJSON()).toEqual(0x12345678);
+    expect(new UInt(registry, '0x1234567890', 64).toJSON()).toEqual(78187493520);
+    expect(new UInt(registry, '0x1234567890abcdef', 64).toJSON()).toEqual('0x1234567890abcdef');
+    expect(new UInt(registry, 1, 256).toJSON()).toEqual('0x0000000000000000000000000000000000000000000000000000000000000001');
+  });
+
+  describe('utilities', (): void => {
+    it('provides a toBigInt interface', (): void => {
+      expect(
+        new UInt(registry, 9876543210123456789n).toBigInt()
+      ).toEqual(9876543210123456789n);
+    });
+
+    it('provides a toBn interface', (): void => {
+      expect(
+        new UInt(registry, 987).toBn().toNumber()
+      ).toEqual(987);
+    });
+
+    it('provides a toNumber interface', (): void => {
+      expect(
+        new UInt(registry, 4567).toNumber()
+      ).toEqual(4567);
+    });
+
+    it('has a working toBigInt', (): void => {
+      expect(
+        new UInt(registry, 4567).toBigInt() + BigInt(1)
+      ).toEqual(BigInt(4568));
+    });
+
+    it('has a sane inspect', (): void => {
+      expect(
+        new UInt(registry, '0x12', 16).inspect()
+      ).toEqual({
+        outer: [new Uint8Array([0x12, 0x00])]
+      });
+    });
+
+    describe('eq', (): void => {
+      const test = new UInt(registry, 12345);
+
+      it('compares against other BN values', (): void => {
+        expect(test.eq(new BN(12345))).toBe(true);
+      });
+
+      it('compares against other number values', (): void => {
+        expect(test.eq(12345)).toBe(true);
+      });
+
+      it('compares against hex values', (): void => {
+        expect(test.eq('0x3039')).toBe(true);
+      });
+    });
+
+    describe('isMax()', (): void => {
+      it('is false where not full', (): void => {
+        expect(new UInt(registry, '0x1234', 32).isMax()).toEqual(false);
+        expect(new UInt(registry, '0xffffff', 32).isMax()).toEqual(false);
+        expect(new UInt(registry, '0x12345678', 32).isMax()).toEqual(false);
+        expect(new UInt(registry, '0xfffffff0', 32).isMax()).toEqual(false);
+      });
+
+      it('is true when full', (): void => {
+        expect(new UInt(registry, '0xffffffff', 32).isMax()).toEqual(true);
+      });
+    });
+  });
+
+  describe('static with', (): void => {
+    it('allows default toRawType', (): void => {
+      expect(
+        new (UInt.with(64))(registry).toRawType()
+      ).toEqual('u64');
+    });
+
+    it('allows toRawType override', (): void => {
+      expect(
+        new (UInt.with(64, 'SomethingElse'))(registry).toRawType()
+      ).toEqual('SomethingElse');
+    });
+
+    it('has proper toHuman() for PerMill/PerBill/Percent/Balance', (): void => {
+      expect(registry.createType('Perbill', 12_340_000).toHuman()).toEqual('1.23%');
+      expect(registry.createType('Percent', 12).toHuman()).toEqual('12.00%');
+      expect(registry.createType('Permill', 16_900).toHuman()).toEqual('1.69%');
+      expect(registry.createType('Balance', '123456789012345').toHuman()).toEqual('123.4567 Unit');
+    });
+  });
+
+  perf('UInt', 75_000, [[new Uint8Array([31, 32, 33, 34])]], (v: Uint8Array) => new UInt(registry, v));
+});

package/src/base/UInt.ts

@@ -0,0 +1,30 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AnyNumber, CodecClass, Registry, UIntBitLength } from '../types/index.js';
+
+import { AbstractInt } from '../abstract/Int.js';
+
+/**
+ * @name UInt
+ * @description
+ * A generic unsigned integer codec. For Bizinikiwi all numbers are Little Endian encoded,
+ * this handles the encoding and decoding of those numbers. Upon construction
+ * the bitLength is provided and any additional use keeps the number to this
+ * length. This extends `BN`, so all methods available on a normal `BN` object
+ * is available here.
+ * @noInheritDoc
+ */
+export class UInt extends AbstractInt {
+  public static with (bitLength: UIntBitLength, typeName?: string): CodecClass<UInt> {
+    return class extends UInt {
+      constructor (registry: Registry, value?: AnyNumber | null) {
+        super(registry, value, bitLength);
+      }
+
+      public override toRawType (): string {
+        return typeName || super.toRawType();
+      }
+    };
+  }
+}