@pezkuwi/types-codec 16.5.17 → 16.5.18

package/src/abstract/index.ts

@@ -0,0 +1,6 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export { AbstractArray } from './Array.js';
+export { AbstractBase } from './Base.js';
+export { AbstractInt } from './Int.js';

package/src/base/Compact.spec.ts

@@ -0,0 +1,99 @@
+// 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 { CodecDate, Compact, U32 } from '@pezkuwi/types-codec';
+import { BN } from '@pezkuwi/util';
+
+import { perf } from '../test/performance.js';
+
+const CompactU32 = Compact.with(U32);
+
+describe('Compact', (): void => {
+  const registry = new TypeRegistry();
+
+  describe('constructor', (): void => {
+    it('fails on > MAX_SAFE_INTEGER', (): void => {
+      // eslint-disable-next-line @typescript-eslint/no-loss-of-precision, no-loss-of-precision
+      expect(() => new Compact(registry, 'u128', 9007199254740999)).toThrow(/integer <= Number.MAX_SAFE_INTEGER/);
+    });
+
+    it('has support for BigInt', (): void => {
+      expect(
+        new Compact(registry, 'u128', 123456789000123456789n).toHuman()
+      ).toEqual('123,456,789,000,123,456,789');
+    });
+
+    it('has the correct bitLength for constructor values (BlockNumber)', (): void => {
+      expect(
+        new (Compact.with(registry.createClass('BlockNumber')))(registry, 0xfffffff9).bitLength()
+      ).toEqual(32);
+    });
+
+    it('has the correct encodedLength for constructor values (string BlockNumber)', (): void => {
+      expect(
+        new (Compact.with('BlockNumber'))(registry, 0xfffffff9).encodedLength
+      ).toEqual(5);
+    });
+
+    it('has the correct encodedLength for constructor values (class BlockNumber)', (): void => {
+      expect(
+        new (Compact.with(registry.createClass('BlockNumber')))(registry, 0xfffffff9).encodedLength
+      ).toEqual(5);
+    });
+
+    it('has the correct encodedLength for constructor values (u32)', (): void => {
+      expect(
+        new (Compact.with(U32))(registry, 0xffff9).encodedLength
+      ).toEqual(4);
+    });
+
+    it('constructs properly via Uint8Array as U32', (): void => {
+      expect(
+        new (Compact.with(U32))(registry, new Uint8Array([254, 255, 3, 0])).toNumber()
+      ).toEqual(new BN(0xffff).toNumber());
+    });
+
+    it('constructs properly via number as Moment', (): void => {
+      expect(
+        new (Compact.with(CodecDate))(registry, 1537968546).toString().startsWith('Wed Sep 26 2018') // The time depends on the timezone this test is run in
+      ).toBe(true);
+    });
+  });
+
+  describe('utils', (): void => {
+    it('compares against another Compact', (): void => {
+      expect(new (Compact.with(U32))(registry, 12345).eq(new (Compact.with(U32))(registry, 12345))).toBe(true);
+    });
+
+    it('compares against a primitive', (): void => {
+      expect(new (Compact.with(U32))(registry, 12345).eq(12345)).toBe(true);
+    });
+
+    it('unwraps to the wrapped value', (): void => {
+      expect(new (Compact.with(U32))(registry, 12345).unwrap() instanceof U32).toBe(true);
+    });
+
+    it('has a valid toBn interface', (): void => {
+      expect(new (Compact.with('u128'))(registry, '12345678987654321').toBn().eq(new BN('12345678987654321'))).toBe(true);
+    });
+
+    it('has a valid toBigInt interface', (): void => {
+      expect(
+        (new (Compact.with('u128'))(registry, 12345678987654321n).toBigInt() + 1n) === 12345678987654322n
+      ).toBe(true);
+    });
+
+    it('has a sane inspect', (): void => {
+      expect(
+        new (Compact.with(U32))(registry, 0xffff).inspect()
+      ).toEqual({
+        outer: [new Uint8Array([254, 255, 3, 0])]
+      });
+    });
+  });
+
+  perf('Compact', 75_000, [[new Uint8Array([63 << 2])]], (v: Uint8Array) => new CompactU32(registry, v));
+});

package/src/base/Compact.ts

@@ -0,0 +1,198 @@
+// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { BN } from '@pezkuwi/util';
+import type { HexString } from '@pezkuwi/util/types';
+import type { AnyJson, AnyNumber, CodecClass, DefinitionSetter, ICompact, Inspect, INumber, IU8a, Registry } from '../types/index.js';
+
+import { compactFromU8a, compactFromU8aLim, compactToU8a, identity, isU8a } from '@pezkuwi/util';
+
+import { typeToConstructor } from '../utils/index.js';
+
+function decodeCompact<T extends INumber> (registry: Registry, Type: CodecClass<T>, value: Compact<T> | AnyNumber): [T, number] {
+  if (isU8a(value)) {
+    const [decodedLength, bn] = (value[0] & 0b11) < 0b11
+      ? compactFromU8aLim(value)
+      : compactFromU8a(value);
+
+    return [new Type(registry, bn), decodedLength];
+  } else if (value instanceof Compact) {
+    const raw = value.unwrap();
+
+    return raw instanceof Type
+      ? [raw, 0]
+      : [new Type(registry, raw), 0];
+  } else if (value instanceof Type) {
+    return [value, 0];
+  }
+
+  return [new Type(registry, value), 0];
+}
+
+/**
+ * @name Compact
+ * @description
+ * A compact length-encoding codec wrapper. It performs the same function as Length, however
+ * differs in that it uses a variable number of bytes to do the actual encoding. This is mostly
+ * used by other types to add length-prefixed encoding, or in the case of wrapped types, taking
+ * a number and making the compact representation thereof
+ */
+export class Compact<T extends INumber> implements ICompact<T> {
+  readonly registry: Registry;
+
+  public createdAtHash?: IU8a;
+  public initialU8aLength?: number;
+  public isStorageFallback?: boolean;
+
+  readonly #Type: CodecClass<T>;
+  readonly #raw: T;
+
+  constructor (registry: Registry, Type: CodecClass<T> | string, value: Compact<T> | AnyNumber = 0, { definition, setDefinition = identity }: DefinitionSetter<CodecClass<T>> = {}) {
+    this.registry = registry;
+    this.#Type = definition || setDefinition(typeToConstructor(registry, Type));
+
+    const [raw, decodedLength] = decodeCompact<T>(registry, this.#Type, value);
+
+    this.initialU8aLength = decodedLength;
+    this.#raw = raw;
+  }
+
+  public static with<O extends INumber> (Type: CodecClass<O> | string): CodecClass<Compact<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 Compact<O> {
+      constructor (registry: Registry, value?: Compact<O> | AnyNumber) {
+        super(registry, Type, value, { definition, setDefinition });
+      }
+    };
+  }
+
+  /**
+   * @description The length of the value when encoded as a Uint8Array
+   */
+  public get encodedLength (): number {
+    return this.toU8a().length;
+  }
+
+  /**
+   * @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.#raw.isEmpty;
+  }
+
+  /**
+   * @description Returns the number of bits in the value
+   */
+  public bitLength (): number {
+    return this.#raw.bitLength();
+  }
+
+  /**
+   * @description Compares the value of the input to see if there is a match
+   */
+  public eq (other?: unknown): boolean {
+    return this.#raw.eq(
+      other instanceof Compact
+        ? other.#raw
+        : other
+    );
+  }
+
+  /**
+   * @description Returns a breakdown of the hex encoding for this Codec
+   */
+  public inspect (): Inspect {
+    return {
+      outer: [this.toU8a()]
+    };
+  }
+
+  /**
+   * @description Returns a BigInt representation of the number
+   */
+  public toBigInt (): bigint {
+    return this.#raw.toBigInt();
+  }
+
+  /**
+   * @description Returns the BN representation of the number
+   */
+  public toBn (): BN {
+    return this.#raw.toBn();
+  }
+
+  /**
+   * @description Returns a hex string representation of the value. isLe returns a LE (number-only) representation
+   */
+  public toHex (isLe?: boolean): HexString {
+    return this.#raw.toHex(isLe);
+  }
+
+  /**
+   * @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.#raw.toHuman(isExtended, disableAscii);
+  }
+
+  /**
+   * @description Converts the Object to JSON, typically used for RPC transfers
+   */
+  public toJSON (): AnyJson {
+    return this.#raw.toJSON();
+  }
+
+  /**
+   * @description Returns the number representation for the value
+   */
+  public toNumber (): number {
+    return this.#raw.toNumber();
+  }
+
+  /**
+   * @description Converts the value in a best-fit primitive form
+   */
+  public toPrimitive (disableAscii?: boolean): string | number {
+    return this.#raw.toPrimitive(disableAscii);
+  }
+
+  /**
+   * @description Returns the base runtime type name for this instance
+   */
+  public toRawType (): string {
+    return `Compact<${this.registry.getClassName(this.#Type) || this.#raw.toRawType()}>`;
+  }
+
+  /**
+   * @description Returns the string representation of the value
+   */
+  public toString (): string {
+    return this.#raw.toString();
+  }
+
+  /**
+   * @description Encodes the value as a Uint8Array as per the SCALE specifications
+   */
+  public toU8a (_isBare?: boolean): Uint8Array {
+    return compactToU8a(this.#raw.toBn());
+  }
+
+  /**
+   * @description Returns the embedded [[UInt]] or [[Moment]] value
+   */
+  public unwrap (): T {
+    return this.#raw;
+  }
+}

package/src/base/DoNotConstruct.spec.ts

@@ -0,0 +1,23 @@
+// 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 { DoNotConstruct } from '@pezkuwi/types-codec';
+
+describe('DoNotConstruct', (): void => {
+  const registry = new TypeRegistry();
+
+  it('does not allow construction', (): void => {
+    expect(
+      () => new (DoNotConstruct.with())(registry)
+    ).toThrow(/Cannot construct unknown type DoNotConstruct/);
+  });
+
+  it('does not allow construction (with Name)', (): void => {
+    expect(
+      () => new (DoNotConstruct.with('Something'))(registry)
+    ).toThrow(/Cannot construct unknown type Something/);
+  });
+});

package/src/base/DoNotConstruct.ts

@@ -0,0 +1,118 @@
+// 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, CodecClass, Inspect, IU8a, Registry } from '../types/index.js';
+
+/**
+ * @name DoNotConstruct
+ * @description
+ * An unknown type that fails on construction with the type info
+ */
+export class DoNotConstruct implements Codec {
+  readonly registry: Registry;
+
+  public createdAtHash?: IU8a;
+  public isStorageFallback?: boolean;
+
+  #neverError: Error;
+
+  constructor (registry: Registry, typeName = 'DoNotConstruct') {
+    this.registry = registry;
+    this.#neverError = new Error(`DoNotConstruct: Cannot construct unknown type ${typeName}`);
+
+    throw this.#neverError;
+  }
+
+  public static with (typeName?: string): CodecClass {
+    return class extends DoNotConstruct {
+      constructor (registry: Registry) {
+        super(registry, typeName);
+      }
+    };
+  }
+
+  /**
+   * @description The length of the value when encoded as a Uint8Array
+   */
+  public get encodedLength (): number {
+    throw this.#neverError;
+  }
+
+  /**
+   * @description returns a hash of the contents
+   */
+  public get hash (): IU8a {
+    throw this.#neverError;
+  }
+
+  /**
+   * @description Checks if the value is an empty value (always true)
+   */
+  public get isEmpty (): boolean {
+    throw this.#neverError;
+  }
+
+  /**
+   * @description Unimplemented
+   */
+  eq (): boolean {
+    throw this.#neverError;
+  }
+
+  /**
+   * @description Unimplemented
+   */
+  public inspect (): Inspect {
+    throw this.#neverError;
+  }
+
+  /**
+   * @description Unimplemented
+   */
+  toHex (): HexString {
+    throw this.#neverError;
+  }
+
+  /**
+   * @description Unimplemented
+   */
+  toHuman (): AnyJson {
+    throw this.#neverError;
+  }
+
+  /**
+   * @description Unimplemented
+   */
+  toJSON (): AnyJson {
+    throw this.#neverError;
+  }
+
+  /**
+   * @description Unimplemented
+   */
+  toPrimitive (): AnyJson {
+    throw this.#neverError;
+  }
+
+  /**
+   * @description Unimplemented
+   */
+  toRawType (): string {
+    throw this.#neverError;
+  }
+
+  /**
+   * @description Unimplemented
+   */
+  toString (): string {
+    throw this.#neverError;
+  }
+
+  /**
+   * @description Unimplemented
+   */
+  toU8a (): Uint8Array {
+    throw this.#neverError;
+  }
+}