@pezkuwi/types-codec 16.5.5

package/src/native/Struct.ts

@@ -0,0 +1,338 @@
+// Copyright 2017-2025 @polkadot/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '@pezkuwi/util/types';
+import type { AnyJson, BareOpts, Codec, CodecClass, DefinitionSetter, Inspect, IStruct, IU8a, Registry } from '../types/index.js';
+
+import { isBoolean, isHex, isObject, isU8a, isUndefined, objectProperties, stringCamelCase, stringify, u8aConcatStrict, u8aToHex, u8aToU8a } from '@pezkuwi/util';
+
+import { compareMap, decodeU8aStruct, mapToTypeMap, typesToMap } from '../utils/index.js';
+
+type TypesDef<T = Codec> = Record<string, string | CodecClass<T>>;
+
+type Definition = [CodecClass[], string[]];
+
+function noopSetDefinition (d: Definition): Definition {
+  return d;
+}
+
+/** @internal */
+function decodeStructFromObject (registry: Registry, [Types, keys]: Definition, value: any, jsonMap: Map<string, string>): [Iterable<[string, Codec]>, number] {
+  let jsonObj: Record<string, unknown> | undefined;
+  const typeofArray = Array.isArray(value);
+  const typeofMap = value instanceof Map;
+  const count = keys.length;
+
+  if (!typeofArray && !typeofMap && !isObject(value)) {
+    throw new Error(`Struct: Cannot decode value ${stringify(value)} (typeof ${typeof value}), expected an input object, map or array`);
+  } else if (typeofArray && value.length !== count) {
+    throw new Error(`Struct: Unable to map ${stringify(value)} array to object with known keys ${keys.join(', ')}`);
+  }
+
+  const raw = new Array<[string, Codec]>(count);
+
+  for (let i = 0; i < count; i++) {
+    const key = keys[i];
+    const jsonKey = jsonMap.get(key) || key;
+    const Type = Types[i];
+    let assign: unknown;
+
+    try {
+      if (typeofArray) {
+        assign = value[i] as unknown;
+      } else if (typeofMap) {
+        assign = jsonKey && value.get(jsonKey);
+      } else {
+        assign = jsonKey && Object.prototype.hasOwnProperty.call(value, jsonKey) ? value[jsonKey] as unknown : undefined;
+
+        if (isUndefined(assign)) {
+          if (isUndefined(jsonObj)) {
+            const entries = Object.entries(value);
+
+            jsonObj = {};
+
+            for (let e = 0, ecount = entries.length; e < ecount; e++) {
+              if (Object.prototype.hasOwnProperty.call(value, entries[e][0])) {
+                jsonObj[stringCamelCase(entries[e][0])] = entries[e][1];
+              }
+            }
+          }
+
+          assign = jsonKey && Object.prototype.hasOwnProperty.call(jsonObj, jsonKey) ? jsonObj[jsonKey] : undefined;
+        }
+      }
+
+      raw[i] = [
+        key,
+        assign instanceof Type
+          ? assign
+          : new Type(registry, assign)
+      ];
+    } catch (error) {
+      let type = Type.name;
+
+      try {
+        type = new Type(registry).toRawType();
+      } catch {
+        // ignore
+      }
+
+      throw new Error(`Struct: failed on ${jsonKey}: ${type}:: ${(error as Error).message}`);
+    }
+  }
+
+  return [raw, 0];
+}
+
+/**
+ * @name Struct
+ * @description
+ * A Struct defines an Object with key-value pairs - where the values are Codec values. It removes
+ * a lot of repetition from the actual coding, define a structure type, pass it the key/Codec
+ * values in the constructor and it manages the decoding. It is important that the constructor
+ * values matches 100% to the order in th Rust code, i.e. don't go crazy and make it alphabetical,
+ * it needs to decoded in the specific defined order.
+ * @noInheritDoc
+ */
+export class Struct<
+  // The actual Class structure, i.e. key -> Class
+  S extends TypesDef = TypesDef,
+  // input values, mapped by key can be anything (construction)
+  V extends { [K in keyof S]: any } = { [K in keyof S]: any },
+  // type names, mapped by key, name of Class in S
+  E extends { [K in keyof S]: string } = { [K in keyof S]: string }> extends Map<keyof S, Codec> implements IStruct<keyof S> {
+  readonly registry: Registry;
+
+  public createdAtHash?: IU8a | undefined;
+  public initialU8aLength?: number;
+  public isStorageFallback?: boolean;
+
+  readonly #jsonMap: Map<keyof S, string>;
+  readonly #Types: Definition;
+
+  constructor (registry: Registry, Types: S, value?: V | Map<unknown, unknown> | unknown[] | HexString | null, jsonMap = new Map<string, string>(), { definition, setDefinition = noopSetDefinition }: DefinitionSetter<Definition> = {}) {
+    const typeMap = definition || setDefinition(mapToTypeMap(registry, Types));
+    const [decoded, decodedLength] = isU8a(value) || isHex(value)
+      ? decodeU8aStruct(registry, new Array<[string, Codec]>(typeMap[0].length), u8aToU8a(value), typeMap)
+      : value instanceof Struct
+        ? [value as Iterable<[string, Codec]>, 0]
+        : decodeStructFromObject(registry, typeMap, value || {}, jsonMap);
+
+    super(decoded);
+
+    this.initialU8aLength = decodedLength;
+    this.registry = registry;
+    this.#jsonMap = jsonMap;
+    this.#Types = typeMap;
+  }
+
+  public static with<S extends TypesDef> (Types: S, jsonMap?: Map<string, string>): CodecClass<Struct<S>> {
+    let definition: Definition | undefined;
+
+    // eslint-disable-next-line no-return-assign
+    const setDefinition = (d: Definition) =>
+      definition = d;
+
+    return class extends Struct<S> {
+      static {
+        const keys = Object.keys(Types);
+
+        objectProperties(this.prototype, keys, (k: string, _: number, self: Struct) =>
+          self.get(k)
+        );
+      }
+
+      constructor (registry: Registry, value?: unknown) {
+        super(registry, Types, value as HexString, jsonMap, { definition, setDefinition });
+      }
+    };
+  }
+
+  /**
+   * @description The available keys for this struct
+   */
+  public get defKeys (): string[] {
+    return this.#Types[1];
+  }
+
+  /**
+   * @description Checks if the value is an empty value '{}'
+   */
+  public get isEmpty (): boolean {
+    return [...this.keys()].length === 0;
+  }
+
+  /**
+   * @description The length of the value when encoded as a Uint8Array
+   */
+  public get encodedLength (): number {
+    let total = 0;
+
+    for (const v of this.values()) {
+      total += v.encodedLength;
+    }
+
+    return total;
+  }
+
+  /**
+   * @description returns a hash of the contents
+   */
+  public get hash (): IU8a {
+    return this.registry.hash(this.toU8a());
+  }
+
+  /**
+   * @description Returns the Type description of the structure
+   */
+  public get Type (): E {
+    const result: Record<string, string> = {};
+    const [Types, keys] = this.#Types;
+
+    for (let i = 0, count = keys.length; i < count; i++) {
+      result[keys[i]] = new Types[i](this.registry).toRawType();
+    }
+
+    return result as E;
+  }
+
+  /**
+   * @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 specific names entry in the structure
+   * @param key The name of the entry to retrieve
+   */
+  public override get (key: keyof S): Codec | undefined {
+    return super.get(key);
+  }
+
+  /**
+   * @description Returns the values of a member at a specific index (Rather use get(name) for performance)
+   */
+  public getAtIndex (index: number): Codec {
+    return this.toArray()[index];
+  }
+
+  /**
+   * @description Returns the a types value by name
+   */
+  public getT <T = Codec> (key: string): T {
+    return super.get(key) as unknown as T;
+  }
+
+  /**
+   * @description Returns a breakdown of the hex encoding for this Codec
+   */
+  public inspect (isBare?: BareOpts): Inspect {
+    const inner: Inspect[] = [];
+
+    for (const [k, v] of this.entries()) {
+      inner.push({
+        ...v.inspect(
+          !isBare || isBoolean(isBare)
+            ? isBare
+            : isBare[k]
+        ),
+        name: stringCamelCase(k as string)
+      });
+    }
+
+    return {
+      inner
+    };
+  }
+
+  /**
+   * @description Converts the Object to an standard JavaScript Array
+   */
+  public toArray (): Codec[] {
+    return [...this.values()];
+  }
+
+  /**
+   * @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 (isExtended?: boolean, disableAscii?: boolean): Record<string, AnyJson> {
+    const json: Record<string, AnyJson> = {};
+
+    for (const [k, v] of this.entries()) {
+      json[k as string] = v.toHuman(isExtended, disableAscii);
+    }
+
+    return json;
+  }
+
+  /**
+   * @description Converts the Object to JSON, typically used for RPC transfers
+   */
+  public toJSON (): Record<string, AnyJson> {
+    const json: Record<string, AnyJson> = {};
+
+    for (const [k, v] of this.entries()) {
+      // Here we pull out the entry against the JSON mapping (if supplied)
+      // since this representation goes over RPC and needs to be correct
+      json[(this.#jsonMap.get(k) || k) as string] = v.toJSON();
+    }
+
+    return json;
+  }
+
+  /**
+   * @description Converts the value in a best-fit primitive form
+   */
+  public toPrimitive (disableAscii?: boolean): Record<string, AnyJson> {
+    const json: Record<string, AnyJson> = {};
+
+    for (const [k, v] of this.entries()) {
+      json[k as string] = v.toPrimitive(disableAscii);
+    }
+
+    return json;
+  }
+
+  /**
+   * @description Returns the base runtime type name for this instance
+   */
+  public toRawType (): string {
+    return stringify(typesToMap(this.registry, this.#Types));
+  }
+
+  /**
+   * @description Returns the string representation of the value
+   */
+  public override toString (): string {
+    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 toU8a (isBare?: BareOpts): Uint8Array {
+    const encoded: Uint8Array[] = [];
+
+    for (const [k, v] of this.entries()) {
+      encoded.push(
+        v.toU8a(
+          !isBare || isBoolean(isBare)
+            ? isBare
+            : isBare[k]
+        )
+      );
+    }
+
+    return u8aConcatStrict(encoded);
+  }
+}

package/src/native/Text.spec.ts

@@ -0,0 +1,85 @@
+// Copyright 2017-2025 @polkadot/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import type { CodecTo } from '@pezkuwi/types-codec/types';
+
+import { TypeRegistry } from '@pezkuwi/types';
+import { Bytes, Raw, Text } from '@pezkuwi/types-codec';
+import { stringToU8a } from '@pezkuwi/util';
+
+import { perf } from '../test/performance.js';
+
+describe('Text', (): void => {
+  const registry = new TypeRegistry();
+
+  describe('decode', (): void => {
+    const testDecode = (type: string, input: null | string | Uint8Array | { toString: () => string }, expected: string, toFn: 'toString' | 'toHex' | 'toHuman' = 'toString'): void =>
+      it(`can decode from ${type}`, (): void => {
+        expect(new Text(registry, input)[toFn]()).toBe(expected);
+      });
+
+    testDecode('string', 'foo', 'foo');
+    testDecode('Text', new Text(registry, 'foo'), 'foo');
+    testDecode('Uint8Array', Uint8Array.from([12, 102, 111, 111]), 'foo');
+    testDecode('Raw', new Raw(registry, Uint8Array.from([102, 111, 111])), 'foo'); // no length
+    testDecode('Raw', new Raw(registry, Uint8Array.from([102, 111, 111])), 'foo', 'toHuman'); // no length
+    testDecode('Bytes', new Bytes(registry, Uint8Array.from([12, 102, 111, 111])), 'foo'); // length-aware encoding
+    testDecode('Bytes', new Bytes(registry, Uint8Array.from([12, 102, 111, 111])), 'foo', 'toHuman'); // length-aware encoding
+    testDecode('object with `toString()`', { toString (): string {
+      return 'foo';
+    } }, 'foo');
+    testDecode('hex input value', new Text(registry, '0x12345678'), '0x12345678', 'toHex');
+    testDecode('null', null, '');
+  });
+
+  describe('encode', (): void => {
+    const testEncode = (to: CodecTo, expected: string | Uint8Array): void =>
+      it(`can encode ${to}`, (): void => {
+        expect(new Text(registry, 'foo')[to]()).toEqual(expected);
+      });
+
+    testEncode('toHex', '0x666f6f');
+    testEncode('toString', 'foo');
+    testEncode('toU8a', Uint8Array.from([12, 102, 111, 111]));
+  });
+
+  describe('utils', (): void => {
+    it('compares actual string values', (): void => {
+      expect(new Text(registry, '123').eq('123')).toBe(true);
+    });
+
+    it('compares actual String values', (): void => {
+      expect(new Text(registry, 'XYX').eq(String('XYX'))).toBe(true);
+    });
+
+    it('compares actual non-string values (fails)', (): void => {
+      expect(new Text(registry, '123').eq(123)).toBe(false);
+    });
+
+    it('calulates the length & encoded length correctly for ASCII', (): void => {
+      const test = new Text(registry, 'abcde');
+
+      expect(test.encodedLength).toEqual(6);
+      expect(test).toHaveLength(5);
+    });
+
+    it('calulates the length & encoded length correctly for non-ASCII', (): void => {
+      const test = new Text(registry, '中文');
+
+      expect(test.encodedLength).toEqual(7);
+      expect(test).toHaveLength(2);
+    });
+
+    it('has a sane inspect', (): void => {
+      expect(
+        new Text(registry, 'abcde').inspect()
+      ).toEqual({
+        outer: [new Uint8Array([5 << 2]), stringToU8a('abcde')]
+      });
+    });
+  });
+
+  perf('Text', 100_000, [[new Uint8Array([6 << 2, 102, 111, 111, 102, 111, 111])]], (v: Uint8Array) => new Text(registry, v));
+});

package/src/native/Text.ts

@@ -0,0 +1,184 @@
+// Copyright 2017-2025 @polkadot/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '@pezkuwi/util/types';
+import type { AnyString, AnyU8a, Inspect, IText, IU8a, Registry } from '../types/index.js';
+
+import { compactAddLength, compactFromU8aLim, compactToU8a, hexToU8a, isHex, isString, isU8a, stringToU8a, u8aToHex, u8aToString } from '@pezkuwi/util';
+
+import { Raw } from './Raw.js';
+
+const MAX_LENGTH = 128 * 1024;
+
+/** @internal */
+function decodeText (value?: null | AnyString | AnyU8a | { toString: () => string }): [string, number] {
+  if (isU8a(value)) {
+    if (!value.length) {
+      return ['', 0];
+    }
+
+    // for Raw, the internal buffer does not have an internal length
+    // (the same applies in e.g. Bytes, where length is added at encoding-time)
+    if (value instanceof Raw) {
+      return [u8aToString(value), 0];
+    }
+
+    const [offset, length] = compactFromU8aLim(value);
+    const total = offset + length;
+
+    if (length > MAX_LENGTH) {
+      throw new Error(`Text: length ${length.toString()} exceeds ${MAX_LENGTH}`);
+    } else if (total > value.length) {
+      throw new Error(`Text: required length less than remainder, expected at least ${total}, found ${value.length}`);
+    }
+
+    return [u8aToString(value.subarray(offset, total)), total];
+  } else if (isHex(value)) {
+    return [u8aToString(hexToU8a(value)), 0];
+  }
+
+  return [value ? value.toString() : '', 0];
+}
+
+/**
+ * @name Text
+ * @description
+ * This is a string wrapper, along with the length. It is used both for strings as well
+ * as items such as documentation. It simply extends the standard JS `String` built-in
+ * object, inheriting all methods exposed from `String`.
+ * @noInheritDoc
+ */
+export class Text extends String implements IText {
+  readonly registry: Registry;
+
+  public createdAtHash?: IU8a;
+  public initialU8aLength?: number;
+  public isStorageFallback?: boolean;
+
+  #override: string | null = null;
+
+  constructor (registry: Registry, value?: null | AnyString | AnyU8a | { toString: () => string }) {
+    const [str, decodedLength] = decodeText(value);
+
+    super(str);
+
+    this.registry = registry;
+    this.initialU8aLength = decodedLength;
+  }
+
+  /**
+   * @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.length === 0;
+  }
+
+  /**
+   * @description The length of the value
+   */
+  public override get length (): number {
+    // only included here since we ignore inherited docs
+    return super.length;
+  }
+
+  /**
+   * @description Compares the value of the input to see if there is a match
+   */
+  public eq (other?: unknown): boolean {
+    return isString(other)
+      ? this.toString() === other.toString()
+      : false;
+  }
+
+  /**
+   * @description Returns a breakdown of the hex encoding for this Codec
+   */
+  public inspect (): Inspect {
+    const value = stringToU8a(super.toString());
+
+    return {
+      outer: value.length
+        ? [compactToU8a(value.length), value]
+        : [compactToU8a(value.length)]
+    };
+  }
+
+  /**
+   * @description Set an override value for this
+   */
+  public setOverride (override: string): void {
+    this.#override = override;
+  }
+
+  /**
+   * @description Returns a hex string representation of the value
+   */
+  public toHex (): HexString {
+    // like with Vec<u8>, when we are encoding to hex, we don't actually add
+    // the length prefix (it is already implied by the actual string length)
+    return u8aToHex(this.toU8a(true));
+  }
+
+  /**
+   * @description Converts the Object to to a human-friendly JSON, with additional fields, expansion and formatting of information
+   */
+  public toHuman (): string {
+    return this.toJSON();
+  }
+
+  /**
+   * @description Converts the Object to JSON, typically used for RPC transfers
+   */
+  public toJSON (): string {
+    return this.toString();
+  }
+
+  /**
+   * @description Converts the value in a best-fit primitive form
+   */
+  public toPrimitive (): string {
+    return this.toJSON();
+  }
+
+  /**
+   * @description Returns the base runtime type name for this instance
+   */
+  public toRawType (): string {
+    return 'Text';
+  }
+
+  /**
+   * @description Returns the string representation of the value
+   */
+  public override toString (): string {
+    return this.#override || super.toString();
+  }
+
+  /**
+   * @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 toU8a (isBare?: boolean): Uint8Array {
+    // NOTE Here we use the super toString (we are not taking overrides into account,
+    // rather encoding the original value the string was constructed with)
+    const encoded = stringToU8a(super.toString());
+
+    return isBare
+      ? encoded
+      : compactAddLength(encoded);
+  }
+}

package/src/native/index.ts

@@ -0,0 +1,11 @@
+// Copyright 2017-2025 @polkadot/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export { bool as Bool, bool } from './Bool.js';
+export { CodecDate, CodecDate as Date } from './Date.js';
+export { Float } from './Float.js';
+export { Json } from './Json.js';
+export { Raw } from './Raw.js';
+export { CodecSet, CodecSet as Set } from './Set.js';
+export { Struct } from './Struct.js';
+export { Text } from './Text.js';

package/src/packageDetect.ts

@@ -0,0 +1,11 @@
+// Copyright 2017-2025 @polkadot/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// Do not edit, auto-generated by @polkadot/dev
+// (packageInfo imports will be kept as-is, user-editable)
+
+import { detectPackage } from '@pezkuwi/util';
+
+import { packageInfo } from './packageInfo.js';
+
+detectPackage(packageInfo, null, []);

package/src/packageInfo.ts

@@ -0,0 +1,6 @@
+// Copyright 2017-2025 @polkadot/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// Do not edit, auto-generated by @polkadot/dev
+
+export const packageInfo = { name: '@pezkuwi/types-codec', path: 'auto', type: 'auto', version: '16.5.5' };

package/src/primitive/F32.ts

@@ -0,0 +1,14 @@
+// Copyright 2017-2025 @polkadot/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { Float } from '../native/Float.js';
+
+/**
+ * @name f32
+ * @description
+ * A 32-bit float
+ */
+export class f32 extends Float.with(32) {
+  // NOTE without this, we cannot properly determine extensions
+  readonly __FloatType = 'f32';
+}

package/src/primitive/F64.ts

@@ -0,0 +1,14 @@
+// Copyright 2017-2025 @polkadot/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { Float } from '../native/Float.js';
+
+/**
+ * @name f64
+ * @description
+ * A 64-bit float
+ */
+export class f64 extends Float.with(64) {
+  // NOTE without this, we cannot properly determine extensions
+  readonly __FloatType = 'f64';
+}

package/src/primitive/I128.ts

@@ -0,0 +1,14 @@
+// Copyright 2017-2025 @polkadot/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { Int } from '../base/Int.js';
+
+/**
+ * @name i128
+ * @description
+ * A 128-bit signed integer
+ */
+export class i128 extends Int.with(128) {
+  // NOTE without this, we cannot properly determine extensions
+  readonly __IntType = 'i128';
+}

package/src/primitive/I16.ts

@@ -0,0 +1,14 @@
+// Copyright 2017-2025 @polkadot/types-codec authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { Int } from '../base/Int.js';
+
+/**
+ * @name i16
+ * @description
+ * A 16-bit signed integer
+ */
+export class i16 extends Int.with(16) {
+  // NOTE without this, we cannot properly determine extensions
+  readonly __IntType = 'i16';
+}