@pezkuwi/types-codec 16.5.6 → 16.5.8

package/src/native/Float.ts

@@ -0,0 +1,136 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '@pezkuwi/util/types';
+import type { AnyFloat, CodecClass, IFloat, Inspect, IU8a, Registry } from '../types/index.js';
+
+import { floatToU8a, isHex, isU8a, u8aToFloat, u8aToHex, u8aToU8a } from '@pezkuwi/util';
+
+interface Options {
+  bitLength?: 32 | 64;
+}
+
+/**
+ * @name Float
+ * @description
+ * A Codec wrapper for F32 & F64 values. You generally don't want to be using
+ * f32/f64 in your runtime, operations on fixed points numbers are preferable. This class
+ * was explicitly added since scale-codec has a flag that enables this and it is available
+ * in some eth_* RPCs
+ */
+export class Float extends Number implements IFloat {
+  readonly encodedLength: number;
+  readonly registry: Registry;
+
+  public createdAtHash?: IU8a;
+  public initialU8aLength?: number;
+  public isStorageFallback?: boolean;
+
+  readonly #bitLength: 32 | 64;
+
+  constructor (registry: Registry, value?: AnyFloat, { bitLength = 32 }: Options = {}) {
+    super(
+      isU8a(value) || isHex(value)
+        ? value.length === 0
+          ? 0
+          : u8aToFloat(u8aToU8a(value), { bitLength })
+        : (value || 0)
+    );
+
+    this.#bitLength = bitLength;
+    this.encodedLength = bitLength / 8;
+    this.initialU8aLength = this.encodedLength;
+    this.registry = registry;
+  }
+
+  public static with (bitLength: 32 | 64): CodecClass<Float> {
+    return class extends Float {
+      constructor (registry: Registry, value?: AnyFloat) {
+        super(registry, value, { bitLength });
+      }
+    };
+  }
+
+  /**
+   * @description returns a hash of the contents
+   */
+  public get hash (): IU8a {
+    return this.registry.hash(this.toU8a());
+  }
+
+  /**
+   * @description Returns true if the type wraps an empty/default all-0 value
+   */
+  get isEmpty (): boolean {
+    return this.valueOf() === 0;
+  }
+
+  /**
+   * @description Compares the value of the input to see if there is a match
+   */
+  public eq (other?: unknown): boolean {
+    return this.valueOf() === Number(other);
+  }
+
+  /**
+   * @description Returns a breakdown of the hex encoding for this Codec
+   */
+  public inspect (): Inspect {
+    return {
+      outer: [this.toU8a()]
+    };
+  }
+
+  /**
+   * @description Returns a hex string representation of the value
+   */
+  public toHex (): HexString {
+    return u8aToHex(this.toU8a());
+  }
+
+  /**
+   * @description Converts the Object to to a human-friendly JSON, with additional fields, expansion and formatting of information
+   */
+  public toHuman (): string {
+    return this.toString();
+  }
+
+  /**
+   * @description Converts the Object to JSON, typically used for RPC transfers
+   */
+  public toJSON (): string {
+    // Not sure if this is actually a hex or a string value
+    // (would need to check against RPCs to see the result here)
+    return this.toHex();
+  }
+
+  /**
+   * @description Returns the number representation (Same as valueOf)
+   */
+  public toNumber (): number {
+    return this.valueOf();
+  }
+
+  /**
+   * @description Converts the value in a best-fit primitive form
+   */
+  public toPrimitive (): number {
+    return this.toNumber();
+  }
+
+  /**
+   * @description Returns the base runtime type name for this instance
+   */
+  public toRawType (): string {
+    return `f${this.#bitLength}`;
+  }
+
+  /**
+   * @description Encodes the value as a Uint8Array as per the SCALE specifications
+   */
+  public toU8a (_isBare?: boolean): Uint8Array {
+    return floatToU8a(this, {
+      bitLength: this.#bitLength
+    });
+  }
+}

package/src/native/Json.ts

@@ -0,0 +1,147 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '@pezkuwi/util/types';
+import type { AnyJson, Codec, Inspect, IU8a, Registry } from '../types/index.js';
+
+import { isFunction, objectProperties, stringify } from '@pezkuwi/util';
+
+import { compareMap } from '../utils/index.js';
+
+/** @internal */
+function decodeJson (value?: Record<string, unknown> | null): [string, any][] {
+  return Object.entries(value || {});
+}
+
+/**
+ * @name Json
+ * @description
+ * Wraps the a JSON structure retrieve via RPC. It extends the standard JS Map with. While it
+ * implements a Codec, it is limited in that it can only be used with input objects via RPC,
+ * i.e. no hex decoding. Unlike a struct, this waps a JSON object with unknown keys
+ * @noInheritDoc
+ */
+export class Json extends Map<string, any> implements Codec {
+  readonly registry: Registry;
+
+  public createdAtHash?: IU8a;
+  public initialU8aLength?: number;
+  public isStorageFallback?: boolean;
+
+  constructor (registry: Registry, value?: Record<string, unknown> | null) {
+    const decoded = decodeJson(value);
+
+    super(decoded);
+
+    this.registry = registry;
+
+    objectProperties(this, decoded.map(([k]) => k), (k) => this.get(k));
+  }
+
+  /**
+   * @description Always 0, never encodes as a Uint8Array
+   */
+  public get encodedLength (): number {
+    return 0 | 0;
+  }
+
+  /**
+   * @description returns a hash of the contents
+   */
+  public get hash (): IU8a {
+    return this.registry.hash(this.toU8a());
+  }
+
+  /**
+   * @description Checks if the value is an empty value
+   */
+  public get isEmpty (): boolean {
+    return [...this.keys()].length === 0;
+  }
+
+  /**
+   * @description Compares the value of the input to see if there is a match
+   */
+  public eq (other?: unknown): boolean {
+    return compareMap(this, other);
+  }
+
+  /**
+   * @description Returns a typed value from the internal map
+   */
+  public getT <T> (key: string): T {
+    return this.get(key) as unknown as T;
+  }
+
+  /**
+   * @description Unimplemented, will throw
+   */
+  public inspect (): Inspect {
+    throw new Error('Unimplemented');
+  }
+
+  /**
+   * @description Unimplemented, will throw
+   */
+  public toHex (): HexString {
+    throw new Error('Unimplemented');
+  }
+
+  /**
+   * @description Converts the Object to a human-friendly JSON, with additional fields, expansion and formatting of information
+   */
+  public toHuman (): Record<string, AnyJson> {
+    return [...this.entries()].reduce<Record<string, AnyJson>>((json, [key, value]): Record<string, AnyJson> => {
+      json[key] = isFunction((value as Codec)?.toHuman)
+        ? (value as Codec).toHuman()
+        : value as AnyJson;
+
+      return json;
+    }, {});
+  }
+
+  /**
+   * @description Converts the Object to JSON, typically used for RPC transfers
+   */
+  public toJSON (): Record<string, AnyJson> {
+    return [...this.entries()].reduce<Record<string, AnyJson>>((json, [key, value]): Record<string, AnyJson> => {
+      json[key] = value as AnyJson;
+
+      return json;
+    }, {});
+  }
+
+  /**
+   * @description Converts the value in a best-fit primitive form
+   */
+  public toPrimitive (disableAscii?: boolean): Record<string, AnyJson> {
+    return [...this.entries()].reduce<Record<string, AnyJson>>((json, [key, value]): Record<string, AnyJson> => {
+      json[key] = isFunction((value as Codec).toPrimitive)
+        ? (value as Codec).toPrimitive(disableAscii)
+        : value as AnyJson;
+
+      return json;
+    }, {});
+  }
+
+  /**
+   * @description Returns the base runtime type name for this instance
+   */
+  public toRawType (): string {
+    return 'Json';
+  }
+
+  /**
+   * @description Returns the string representation of the value
+   */
+  public override toString (): string {
+    return stringify(this.toJSON());
+  }
+
+  /**
+   * @description Unimplemented, will throw
+   */
+  public toU8a (_isBare?: boolean): Uint8Array {
+    throw new Error('Unimplemented');
+  }
+}

package/src/native/Raw.spec.ts

@@ -0,0 +1,113 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import type { AnyU8a, CodecTo } from '@pezkuwi/types-codec/types';
+
+import { TypeRegistry } from '@pezkuwi/types';
+import { Raw } from '@pezkuwi/types-codec';
+
+const registry = new TypeRegistry();
+
+const testDecode = (type: string, input: AnyU8a, expected: string): void =>
+  it(`can decode from ${type}`, (): void => {
+    const e = new Raw(registry, input);
+
+    expect(e.toString()).toBe(expected);
+  });
+
+const testEncode = (to: CodecTo, expected: AnyU8a): void =>
+  it(`can encode ${to}`, (): void => {
+    const e = new Raw(registry, [1, 2, 3, 4, 5]);
+
+    expect(e[to]()).toEqual(expected);
+  });
+
+describe('Raw', (): void => {
+  let u8a: Raw;
+
+  beforeEach((): void => {
+    u8a = new Raw(registry, [1, 2, 3, 4, 5]);
+  });
+
+  testDecode('Array', [1, 2, 3, 4, 5], '0x0102030405');
+  testDecode('hex', '0x0102030405', '0x0102030405');
+  testDecode('U8a', new Uint8Array([1, 2, 3, 4, 5]), '0x0102030405');
+  testDecode('Uint8Array', Uint8Array.from([1, 2, 3, 4, 5]), '0x0102030405');
+
+  testEncode('toJSON', '0x0102030405');
+  testEncode('toHex', '0x0102030405');
+  testEncode('toPrimitive', '0x0102030405');
+  testEncode('toString', '0x0102030405');
+  testEncode('toU8a', Uint8Array.from([1, 2, 3, 4, 5]));
+
+  it('contains the length of the elements', (): void => {
+    expect(u8a.length).toEqual(5);
+  });
+
+  it('correctly encodes length', (): void => {
+    expect(u8a.encodedLength).toEqual(5);
+  });
+
+  it('allows wrapping of a pre-existing instance', (): void => {
+    expect(
+      new Raw(registry, u8a).length
+    ).toEqual(5);
+  });
+
+  it('implements subarray correctly', (): void => {
+    expect(u8a.subarray(1, 3)).toEqual(Uint8Array.from([2, 3]));
+  });
+
+  describe('utils', (): void => {
+    it('compares against other U8a', (): void => {
+      expect(u8a.eq(new Uint8Array([1, 2, 3, 4, 5]))).toBe(true);
+    });
+
+    it('compares against other U8a (non-length)', (): void => {
+      expect(u8a.eq(new Uint8Array([1, 2, 3, 4]))).toBe(false);
+    });
+
+    it('compares against other U8a (mismatch)', (): void => {
+      expect(u8a.eq(new Uint8Array([1, 2, 3, 4, 6]))).toBe(false);
+    });
+
+    it('compares against hex inputs', (): void => {
+      expect(u8a.eq('0x0102030405')).toBe(true);
+    });
+
+    it('has valid isAscii', (): void => {
+      expect(u8a.isAscii).toBe(false);
+      expect(new Raw(registry, '0x2021222324').isAscii).toBe(true);
+    });
+
+    it('has valid toHuman with disableAscii option set as true', (): void => {
+      expect(new Raw(registry, new Uint8Array([85, 85, 85, 85, 85, 85, 85, 85])).toHuman(undefined, true)).toEqual('0x5555555555555555');
+    });
+
+    it('has valid toPrimitive', (): void => {
+      expect(new Raw(registry, 'testing').toPrimitive()).toEqual('testing');
+      expect(new Raw(registry, '0xe4bda0e5a5bd').toPrimitive()).toEqual('0xe4bda0e5a5bd');
+    });
+
+    it('has valid toUtf8', (): void => {
+      expect(new Raw(registry, 'Приветствую, ми').toUtf8()).toEqual('Приветствую, ми');
+      expect(new Raw(registry, '0xe4bda0e5a5bd').toUtf8()).toEqual('你好');
+    });
+
+    it('throws on invalid utf8', (): void => {
+      expect(
+        () => new Raw(registry, '0x7f07b1f87709608bee603bbc79a0dfc29cd315c1351a83aa31adf7458d7d3003').toUtf8()
+      ).toThrow(/The character sequence is not a valid Utf8 string/);
+    });
+
+    it('has a sane inspect', (): void => {
+      expect(
+        new Raw(registry, [1, 2, 3, 4, 5]).inspect()
+      ).toEqual({
+        outer: [new Uint8Array([1, 2, 3, 4, 5])]
+      });
+    });
+  });
+});

package/src/native/Raw.ts

@@ -0,0 +1,171 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '@pezkuwi/util/types';
+import type { AnyJson, AnyU8a, Inspect, IU8a, Registry } from '../types/index.js';
+
+import { isAscii, isUndefined, isUtf8, u8aToHex, u8aToString, u8aToU8a } from '@pezkuwi/util';
+
+/**
+ * @name Raw
+ * @description
+ * A basic wrapper around Uint8Array, with no frills and no fuss. It does differ
+ * from other implementations where it will consume the full Uint8Array as passed to it.
+ * As such it is meant to be subclassed where the wrapper takes care of the
+ * actual lengths instead of used directly.
+ * @noInheritDoc
+ */
+export class Raw extends Uint8Array implements IU8a {
+  readonly registry: Registry;
+
+  public createdAtHash?: IU8a | undefined;
+  public initialU8aLength?: number | undefined;
+  public isStorageFallback?: boolean;
+
+  /**
+   * @description This ensures that operators such as clice, filter, map, etc. return
+   * new Array instances (without this we need to apply overrides)
+   */
+  static get [Symbol.species] (): typeof Uint8Array {
+    return Uint8Array;
+  }
+
+  constructor (registry: Registry, value?: AnyU8a, initialU8aLength?: number) {
+    super(u8aToU8a(value));
+
+    this.registry = registry;
+    this.initialU8aLength = initialU8aLength;
+  }
+
+  /**
+   * @description The length of the value when encoded as a Uint8Array
+   */
+  public get encodedLength (): number {
+    return this.length;
+  }
+
+  /**
+   * @description returns a hash of the contents
+   */
+  public get hash (): IU8a {
+    return this.registry.hash(this.toU8a());
+  }
+
+  /**
+   * @description Returns true if the wrapped value contains only ASCII printable characters
+   */
+  public get isAscii (): boolean {
+    return isAscii(this);
+  }
+
+  /**
+   * @description Returns true if the type wraps an empty/default all-0 value
+   */
+  public get isEmpty (): boolean {
+    return !this.length || isUndefined(this.find((b) => !!b));
+  }
+
+  /**
+   * @description Returns true if the wrapped value contains only utf8 characters
+   */
+  public get isUtf8 (): boolean {
+    return isUtf8(this);
+  }
+
+  /**
+   * @description Returns the number of bits in the value
+   */
+  public bitLength (): number {
+    return this.length * 8;
+  }
+
+  /**
+   * @description Compares the value of the input to see if there is a match
+   */
+  public eq (other?: unknown): boolean {
+    if (other instanceof Uint8Array) {
+      return (this.length === other.length) &&
+        !this.some((b, index) => b !== other[index]);
+    }
+
+    return this.eq(u8aToU8a(other as string));
+  }
+
+  /**
+   * @description Returns a breakdown of the hex encoding for this Codec
+   */
+  public inspect (): Inspect {
+    return {
+      outer: [this.toU8a()]
+    };
+  }
+
+  /**
+   * @description Returns a hex string representation of the value
+   */
+  public toHex (): HexString {
+    return u8aToHex(this);
+  }
+
+  /**
+   * @description Converts the Object to to a human-friendly JSON, with additional fields, expansion and formatting of information
+   */
+  public toHuman (_isExtended?: boolean, disableAscii?: boolean): AnyJson {
+    return this.toPrimitive(disableAscii);
+  }
+
+  /**
+   * @description Converts the Object to JSON, typically used for RPC transfers
+   */
+  public toJSON (): string {
+    return this.toHex();
+  }
+
+  /**
+   * @description Converts the value in a best-fit primitive form
+   */
+  public toPrimitive (disableAscii?: boolean): AnyJson {
+    if (!disableAscii && this.isAscii) {
+      const text = this.toUtf8();
+
+      // ensure we didn't end up with multibyte codepoints
+      if (isAscii(text)) {
+        return text;
+      }
+    }
+
+    return this.toJSON();
+  }
+
+  /**
+   * @description Returns the base runtime type name for this instance
+   */
+  public toRawType (): string {
+    return 'Raw';
+  }
+
+  /**
+   * @description Returns the string representation of the value
+   */
+  public override toString (): string {
+    return this.toHex();
+  }
+
+  /**
+   * @description Encodes the value as a Uint8Array as per the SCALE specifications
+   */
+  public toU8a (_isBare?: boolean): Uint8Array {
+    return Uint8Array.from(this);
+  }
+
+  /**
+   * @description Returns the wrapped data as a UTF-8 string
+   */
+  public toUtf8 (): string {
+    if (!this.isUtf8) {
+      throw new Error('The character sequence is not a valid Utf8 string');
+    }
+
+    return u8aToString(this);
+  }
+}

package/src/native/Set.spec.ts

@@ -0,0 +1,116 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+/* eslint-disable sort-keys */
+
+import { TypeRegistry } from '@pezkuwi/types';
+import { CodecSet } from '@pezkuwi/types-codec';
+import { stringify } from '@pezkuwi/util';
+
+// TODO actually import these from definitions, don't re-define here
+const SET_FIELDS = {
+  header: 0b00000001,
+  body: 0b00000010,
+  receipt: 0b00000100,
+  messageQueue: 0b00001000,
+  justification: 0b00010000
+};
+const SET_ROLES = {
+  none: 0b00000000,
+  full: 0b00000001,
+  light: 0b00000010,
+  authority: 0b00000100
+};
+const SET_WITHDRAW = {
+  TransactionPayment: 0b00000001,
+  Transfer: 0b00000010,
+  Reserve: 0b00000100,
+  Fee: 0b00001000
+};
+
+describe('Set', (): void => {
+  const registry = new TypeRegistry();
+
+  it('constructs via an string[]', (): void => {
+    const set = new CodecSet(registry, SET_ROLES, ['full', 'authority']);
+
+    expect(set.isEmpty).toEqual(false);
+    expect(set.toString()).toEqual(
+      '[full, authority]'
+    );
+  });
+
+  it('throws with invalid values', (): void => {
+    expect(
+      () => new CodecSet(registry, SET_ROLES, ['full', 'authority', 'invalid'])
+    ).toThrow(/Invalid key 'invalid'/);
+  });
+
+  it('throws with add on invalid', (): void => {
+    expect(
+      () => (new CodecSet(registry, SET_ROLES, [])).add('invalid')
+    ).toThrow(/Invalid key 'invalid'/);
+  });
+
+  it('allows construction via number', (): void => {
+    expect(
+      (new CodecSet(registry, SET_WITHDRAW, 15)).eq(['TransactionPayment', 'Transfer', 'Reserve', 'Fee'])
+    ).toBe(true);
+  });
+
+  it('does not allow invalid number', (): void => {
+    expect(
+      () => new CodecSet(registry, SET_WITHDRAW, 31)
+    ).toThrow(/Mismatch decoding '31', computed as '15'/);
+  });
+
+  it('hash a valid encoding', (): void => {
+    const set = new CodecSet(registry, SET_FIELDS, ['header', 'body', 'justification']);
+
+    expect(set.toU8a()).toEqual(new Uint8Array([19]));
+  });
+
+  describe('utils', (): void => {
+    const set = new CodecSet(registry, SET_ROLES, ['full', 'authority']);
+
+    it('compares against string array', (): void => {
+      expect(
+        set.eq(['authority', 'full'])
+      ).toBe(true);
+    });
+
+    it('compares against number (encoded)', (): void => {
+      expect(
+        set.eq(SET_ROLES.full | SET_ROLES.authority)
+      ).toBe(true);
+    });
+
+    it('compares against other sets', (): void => {
+      expect(
+        set.eq(new CodecSet(registry, SET_ROLES, ['authority', 'full']))
+      ).toBe(true);
+    });
+
+    it('returns false on other values', (): void => {
+      expect(
+        set.eq('full')
+      ).toBe(false);
+    });
+
+    it('has a sane inspect', (): void => {
+      expect(set.inspect()).toEqual({
+        outer: [new Uint8Array([SET_ROLES.full | SET_ROLES.authority])]
+      });
+    });
+  });
+
+  it('has a sane toRawType representation', (): void => {
+    expect(
+      new CodecSet(registry, { a: 1, b: 2, c: 345 }).toRawType()
+    ).toEqual(stringify({
+      _set: { a: 1, b: 2, c: 345 }
+    }));
+  });
+});