@pezkuwi/types-codec 16.5.8 → 16.5.9

package/src/base/Null.spec.ts

@@ -1,41 +0,0 @@
-// 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 { Null } from '@pezkuwi/types-codec';
-
-describe('Null', (): void => {
-  const registry = new TypeRegistry();
-
-  it('compares against null', (): void => {
-    expect(new Null(registry).eq(null)).toBe(true);
-  });
-
-  it('compares against Null', (): void => {
-    expect(new Null(registry).eq(new Null(registry))).toBe(true);
-  });
-
-  it('compares against other (failed)', (): void => {
-    expect(new Null(registry).eq()).toBe(false);
-  });
-
-  it('has no hash', (): void => {
-    expect(
-      () => new Null(registry).hash
-    ).toThrow();
-  });
-
-  it('isEmpty', (): void => {
-    expect(new Null(registry).isEmpty).toBe(true);
-  });
-
-  it('has an empty hex', (): void => {
-    expect(new Null(registry).toHex()).toEqual('0x');
-  });
-
-  it('has a Null type', (): void => {
-    expect(new Null(registry).toRawType()).toEqual('Null');
-  });
-});

package/src/base/Null.ts

@@ -1,96 +0,0 @@
-// Copyright 2017-2025 @pezkuwi/types-codec authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-import type { HexString } from '@pezkuwi/util/types';
-import type { Codec, Inspect, IU8a, Registry } from '../types/index.js';
-
-import { isNull } from '@pezkuwi/util';
-
-/**
- * @name Null
- * @description
- * Implements a type that does not contain anything (apart from `null`)
- */
-export class Null implements Codec {
-  readonly encodedLength = 0;
-  readonly isEmpty = true;
-  readonly registry: Registry;
-
-  public createdAtHash?: IU8a;
-  public initialU8aLength = 0;
-  public isStorageFallback?: boolean;
-
-  constructor (registry: Registry) {
-    this.registry = registry;
-  }
-
-  /**
-   * @description returns a hash of the contents
-   */
-  public get hash (): IU8a {
-    throw new Error('.hash is not implemented on Null');
-  }
-
-  /**
-   * @description Compares the value of the input to see if there is a match
-   */
-  public eq (other?: unknown): boolean {
-    return other instanceof Null || isNull(other);
-  }
-
-  /**
-   * @description Returns a breakdown of the hex encoding for this Codec
-   */
-  public inspect (): Inspect {
-    return {};
-  }
-
-  /**
-   * @description Returns a hex string representation of the value
-   */
-  public toHex (): HexString {
-    return '0x';
-  }
-
-  /**
-   * @description Converts the Object to to a human-friendly JSON, with additional fields, expansion and formatting of information
-   */
-  public toHuman (): null {
-    return this.toJSON();
-  }
-
-  /**
-   * @description Converts the Object to JSON, typically used for RPC transfers
-   */
-  public toJSON (): null {
-    return null;
-  }
-
-  /**
-   * @description Converts the value in a best-fit primitive form
-   */
-  public toPrimitive (): null {
-    return null;
-  }
-
-  /**
-   * @description Returns the base runtime type name for this instance
-   */
-  public toRawType (): string {
-    return 'Null';
-  }
-
-  /**
-   * @description Returns the string representation of the value
-   */
-  public toString (): string {
-    return '';
-  }
-
-  /**
-   * @description Encodes the value as a Uint8Array as per the SCALE specifications
-   */
-  public toU8a (_isBare?: boolean): Uint8Array {
-    return new Uint8Array();
-  }
-}

package/src/base/Option.spec.ts

@@ -1,216 +0,0 @@
-// 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 { bool, Bytes, Null, Option, Text, U32 } from '@pezkuwi/types-codec';
-
-const registry = new TypeRegistry();
-
-const testDecode = (type: string, input: any, expected: string): void =>
-  it(`can decode from ${type}`, (): void => {
-    const o = new Option(registry, Text, input);
-
-    expect(o.toString()).toBe(expected);
-    expect(o.isNone).toBe(!expected.length);
-  });
-
-const testEncode = (to: 'toHex' | 'toString' | 'toU8a', expected: any): void =>
-  it(`can encode ${to}`, (): void => {
-    const e = new Option(registry, Text, 'foo');
-
-    expect(e[to]()).toEqual(expected);
-  });
-
-describe('Option', (): void => {
-  it('converts undefined/null to empty', (): void => {
-    expect(new Option(registry, Text, undefined).isNone).toBe(true);
-    expect(new Option(registry, Text, null).isNone).toBe(true);
-    expect(new Option(registry, Text, 'test').isNone).toBe(false);
-    expect(new Option(registry, Text, '0x').isNone).toBe(true);
-    expect(new Option(registry, '()', null).isNone).toBe(true);
-  });
-
-  it('can wrap an Option<Null>/Option<()>', (): void => {
-    [
-      new Option(registry, Null, new Null(registry)),
-      new Option(registry, '()', new Null(registry))
-    ].forEach((test): void => {
-      expect(test.isSome).toBe(true);
-      expect(test.isNone).toBe(false);
-      expect(test.isEmpty).toBe(false);
-      expect(test.toU8a()).toEqual(new Uint8Array([1]));
-      expect(test.unwrap().toHex()).toEqual('0x');
-    });
-  });
-
-  it('can decode a nested Option', (): void => {
-    expect(
-      new Option(
-        registry,
-        Option.with(Option.with(Text)),
-        new Option(
-          registry,
-          Option.with(Text),
-          new Option(
-            registry,
-            Text,
-            new Uint8Array([1, 3 << 2, 66, 67, 68])
-          )
-        )
-      ).toU8a()
-    ).toEqual(new Uint8Array([1, 1, 1, 3 << 2, 66, 67, 68]));
-  });
-
-  it('can convert between different Some/None', (): void => {
-    const def = '{ "foo":"Text", "zar":"Text" }';
-    const none = new Option(registry, def, null);
-    const some = new Option(registry, def, new Option(registry, def, { foo: 'a', zar: 'b' }));
-
-    expect(new Option(registry, def, none).isNone).toBe(true);
-    expect(new Option(registry, def, some).isNone).toBe(false);
-    expect(new Option(registry, def, some).unwrap().toHuman()).toEqual({ foo: 'a', zar: 'b' });
-  });
-
-  it('correctly handles booleans', (): void => {
-    expect(new Option(registry, bool).isNone).toBe(true);
-    expect(new Option(registry, bool, true).isSome).toBe(true);
-    expect(new Option(registry, bool, true).unwrap().isTrue).toBe(true);
-    expect(new Option(registry, bool, false).isSome).toBe(true);
-    expect(new Option(registry, bool, false).unwrap().isTrue).toBe(false);
-  });
-
-  it('converts an option to an option', (): void => {
-    expect(
-      new Option(registry, Text, new Option(registry, Text, 'hello')).toString()
-    ).toEqual('hello');
-  });
-
-  it('converts an option to an option (strings)', (): void => {
-    expect(
-      new Option(registry, 'Text', new Option(registry, 'Text', 'hello')).toString()
-    ).toEqual('hello');
-  });
-
-  it('converts correctly from hex with toHex (Bytes)', (): void => {
-    // Option<Bytes> for a teyrchain head, however, this is effectively an
-    // Option<Option<Bytes>> (hence the length, since it is from storage)
-    const HEX = '0x210100000000000000000000000000000000000000000000000000000000000000000000000000000000011b4d03dd8c01f1049143cf9c4c817e4b167f1d1b83e5c6f0f10d89ba1e7bce';
-
-    // watch the hex prefix and length
-    expect(
-      new Option(registry, Bytes, HEX).toHex().substring(6)
-    ).toEqual(HEX.substring(2));
-  });
-
-  it('converts correctly from hex with toNumber (U64)', (): void => {
-    const HEX = '0x12345678';
-
-    expect(
-      new Option(registry, U32, HEX).unwrap().toNumber()
-    ).toEqual(0x12345678);
-  });
-
-  it('decodes reusing instanciated inputs', (): void => {
-    const foo = new Text(registry, 'bar');
-
-    expect(
-      (new Option(registry, Text, foo)).value
-    ).toBe(foo);
-  });
-
-  testDecode('string (with)', 'foo', 'foo');
-  testDecode('string (without)', undefined, '');
-  testDecode('Uint8Array (with)', Uint8Array.from([1, 12, 102, 111, 111]), 'foo');
-  testDecode('Uint8Array (without)', Uint8Array.from([0]), '');
-
-  testEncode('toHex', '0x0c666f6f');
-  testEncode('toString', 'foo');
-  testEncode('toU8a', Uint8Array.from([1, 12, 102, 111, 111]));
-
-  it('has empty toString() (undefined)', (): void => {
-    expect(
-      new Option(registry, Text).toString()
-    ).toEqual('');
-  });
-
-  it('has value toString() (provided)', (): void => {
-    expect(
-      new Option(registry, Text, new Uint8Array([1, 4 << 2, 49, 50, 51, 52])).toString()
-    ).toEqual('1234');
-  });
-
-  it('converts toU8a() with', (): void => {
-    expect(
-      new Option(registry, Text, '1234').toU8a()
-    ).toEqual(new Uint8Array([1, 4 << 2, 49, 50, 51, 52]));
-  });
-
-  it('allows bare specifiers on toU8a', (): void => {
-    expect(
-      new Option(registry, Text, '1234').toU8a(true)
-    ).toEqual(new Uint8Array([49, 50, 51, 52]));
-  });
-
-  it('converts toU8a() without', (): void => {
-    expect(
-      new Option(registry, Text).toU8a()
-    ).toEqual(new Uint8Array([0]));
-  });
-
-  it('converts toJSON() as null without', (): void => {
-    expect(
-      new Option(registry, Text).toJSON()
-    ).toEqual(null);
-  });
-
-  it('converts toJSON() as non-null with Bytes', (): void => {
-    expect(
-      new Option(registry, Bytes, 'abcde').toJSON()
-    ).toEqual('0x6162636465');
-  });
-
-  it('converts toJSON() as non-null with Text', (): void => {
-    expect(
-      new Option(registry, Text, 'abcde').toJSON()
-    ).toEqual('abcde');
-  });
-
-  describe('utils', (): void => {
-    const test = new Option(registry, Text, '1234');
-
-    it('compares against other option', (): void => {
-      expect(test.eq(new Option(registry, Text, '1234'))).toBe(true);
-    });
-
-    it('compares against raw value', (): void => {
-      expect(test.eq('1234')).toBe(true);
-    });
-
-    it('unwrapOr to specified if empty', (): void => {
-      expect(new Option(registry, Text).unwrapOr('6789').toString()).toEqual('6789');
-    });
-
-    it('unwrapOr to specified if non-empty', (): void => {
-      expect(new Option(registry, Text, '1234').unwrapOr(null)?.toString()).toEqual('1234');
-    });
-
-    it('unwrapOrDefault to default if empty', (): void => {
-      expect(new Option(registry, U32).unwrapOrDefault().toNumber()).toEqual(0);
-    });
-
-    it('unwrapOrDefault to specified if non-empty', (): void => {
-      expect(new Option(registry, U32, '1234').unwrapOrDefault().toNumber()).toEqual(1234);
-    });
-
-    it('has a sane inspect', (): void => {
-      expect(
-        new Option(registry, U32, '1234').inspect()
-      ).toEqual({
-        inner: undefined,
-        outer: [new Uint8Array([0x01]), new Uint8Array([210, 4, 0, 0])]
-      });
-    });
-  });
-});

package/src/base/Option.ts

@@ -1,275 +0,0 @@
-// 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, DefinitionSetter, Inspect, IOption, IU8a, Registry } from '../types/index.js';
-
-import { identity, isCodec, isNull, isU8a, isUndefined, u8aToHex } from '@pezkuwi/util';
-
-import { typeToConstructor } from '../utils/index.js';
-import { Null } from './Null.js';
-
-class None extends Null {
-  /**
-   * @description Returns the base runtime type name for this instance
-   */
-  public override toRawType (): string {
-    return 'None';
-  }
-}
-
-/** @internal */
-function decodeOption (registry: Registry, Type: CodecClass, value?: unknown): Codec {
-  if (value instanceof Type) {
-    // don't re-create, use as it (which also caters for derived types)
-    return value;
-  } else if (value instanceof Option) {
-    if (value.value instanceof Type) {
-      // same instance, return it
-      return value.value;
-    } else if (value.isNone) {
-      // internal is None, we are also none
-      return new None(registry);
-    }
-
-    // convert the actual value into known
-    return new Type(registry, value.value);
-  } else if (isNull(value) || isUndefined(value) || value === '0x' || value instanceof None) {
-    // anything empty we pass as-is
-    return new None(registry);
-  } else if (isU8a(value)) {
-    // the isU8a check happens last in the if-tree - since the wrapped value
-    // may be an instance of it, so Type and Option checks go in first
-    return !value.length || value[0] === 0
-      ? new None(registry)
-      : new Type(registry, value.subarray(1));
-  }
-
-  return new Type(registry, value);
-}
-
-/**
- * @name Option
- * @description
- * An Option is an optional field. Basically the first byte indicates that there is
- * is value to follow. If the byte is `1` there is an actual value. So the Option
- * implements that - decodes, checks for optionality and wraps the required structure
- * with a value if/as required/found.
- */
-export class Option<T extends Codec> implements IOption<T> {
-  readonly registry: Registry;
-
-  public createdAtHash?: IU8a;
-  public initialU8aLength?: number;
-  public isStorageFallback?: boolean;
-
-  readonly #Type: CodecClass<T>;
-  readonly #raw: T;
-
-  constructor (registry: Registry, typeName: CodecClass<T> | string, value?: unknown, { definition, setDefinition = identity }: DefinitionSetter<CodecClass<T>> = {}) {
-    const Type = definition || setDefinition(typeToConstructor(registry, typeName));
-    const decoded = isU8a(value) && value.length && !isCodec(value)
-      ? value[0] === 0
-        ? new None(registry)
-        : new Type(registry, value.subarray(1))
-      : decodeOption(registry, Type, value);
-
-    this.registry = registry;
-    this.#Type = Type;
-    this.#raw = decoded as T;
-
-    if (decoded?.initialU8aLength) {
-      this.initialU8aLength = 1 + decoded.initialU8aLength;
-    }
-  }
-
-  public static with<O extends Codec> (Type: CodecClass<O> | string): CodecClass<Option<O>> {
-    let definition: CodecClass<O> | undefined;
-
-    const setDefinition = <T> (d: CodecClass<T>): CodecClass<T> => {
-      definition = d as unknown as CodecClass<O>;
-
-      return d;
-    };
-
-    return class extends Option<O> {
-      constructor (registry: Registry, value?: unknown) {
-        super(registry, Type, value, { definition, setDefinition });
-      }
-    };
-  }
-
-  /**
-   * @description The length of the value when encoded as a Uint8Array
-   */
-  public get encodedLength (): number {
-    // boolean byte (has value, doesn't have) along with wrapped length
-    return 1 + this.#raw.encodedLength;
-  }
-
-  /**
-   * @description returns a hash of the contents
-   */
-  public get hash (): IU8a {
-    return this.registry.hash(this.toU8a());
-  }
-
-  /**
-   * @description Checks if the Option has no value
-   */
-  public get isEmpty (): boolean {
-    return this.isNone;
-  }
-
-  /**
-   * @description Checks if the Option has no value
-   */
-  public get isNone (): boolean {
-    return this.#raw instanceof None;
-  }
-
-  /**
-   * @description Checks if the Option has a value
-   */
-  public get isSome (): boolean {
-    return !this.isNone;
-  }
-
-  /**
-   * @description The actual value for the Option
-   */
-  public get value (): T {
-    return this.#raw;
-  }
-
-  /**
-   * @description Compares the value of the input to see if there is a match
-   */
-  public eq (other?: unknown): boolean {
-    if (other instanceof Option) {
-      return (this.isSome === other.isSome) && this.value.eq(other.value);
-    }
-
-    return this.value.eq(other);
-  }
-
-  /**
-   * @description Returns a breakdown of the hex encoding for this Codec
-   */
-  public inspect (): Inspect {
-    if (this.isNone) {
-      return { outer: [new Uint8Array([0])] };
-    }
-
-    const { inner, outer = [] } = this.#raw.inspect();
-
-    return {
-      inner,
-      outer: [new Uint8Array([1]), ...outer]
-    };
-  }
-
-  /**
-   * @description Returns a hex string representation of the value
-   */
-  public toHex (): HexString {
-    // This attempts to align with the JSON encoding - actually in this case
-    // the isSome value is correct, however the `isNone` may be problematic
-    return this.isNone
-      ? '0x'
-      : u8aToHex(this.toU8a().subarray(1));
-  }
-
-  /**
-   * @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.isNone
-      ? null
-      : this.#raw.toJSON();
-  }
-
-  /**
-   * @description Converts the value in a best-fit primitive form
-   */
-  public toPrimitive (disableAscii?: boolean): AnyJson {
-    return this.isNone
-      ? null
-      : this.#raw.toPrimitive(disableAscii);
-  }
-
-  /**
-   * @description Returns the base runtime type name for this instance
-   */
-  public toRawType (isBare?: boolean): string {
-    const wrapped = this.registry.getClassName(this.#Type) || new this.#Type(this.registry).toRawType();
-
-    return isBare
-      ? wrapped
-      : `Option<${wrapped}>`;
-  }
-
-  /**
-   * @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
-   * @param isBare true when the value has none of the type-specific prefixes (internal)
-   */
-  public toU8a (isBare?: boolean): Uint8Array {
-    if (isBare) {
-      return this.#raw.toU8a(true);
-    }
-
-    const u8a = new Uint8Array(this.encodedLength);
-
-    if (this.isSome) {
-      u8a.set([1]);
-      u8a.set(this.#raw.toU8a(), 1);
-    }
-
-    return u8a;
-  }
-
-  /**
-   * @description Returns the value that the Option represents (if available), throws if null
-   */
-  public unwrap (): T {
-    if (this.isNone) {
-      throw new Error('Option: unwrapping a None value');
-    }
-
-    return this.#raw;
-  }
-
-  /**
-   * @description Returns the value that the Option represents (if available) or defaultValue if none
-   * @param defaultValue The value to return if the option isNone
-   */
-  public unwrapOr<O> (defaultValue: O): T | O {
-    return this.isSome
-      ? this.unwrap()
-      : defaultValue;
-  }
-
-  /**
-   * @description Returns the value that the Option represents (if available) or defaultValue if none
-   * @param defaultValue The value to return if the option isNone
-   */
-  public unwrapOrDefault (): T {
-    return this.isSome
-      ? this.unwrap()
-      : new this.#Type(this.registry);
-  }
-}

package/src/base/Result.spec.ts

@@ -1,64 +0,0 @@
-// 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 { Result, Text, u32 } from '@pezkuwi/types-codec';
-import { hexToString } from '@pezkuwi/util';
-
-describe('Result', (): void => {
-  const registry = new TypeRegistry();
-  const Type = Result.with({ Err: Text, Ok: u32 });
-
-  it('has a sane toRawType representation', (): void => {
-    expect(new Type(registry).toRawType()).toEqual('Result<u32,Text>');
-  });
-
-  it('decodes from a u8a (success)', (): void => {
-    const result = new Type(registry, new Uint8Array([0, 1, 2, 3, 4]));
-
-    expect(result.isOk).toBe(true);
-    expect(result.asOk.toU8a()).toEqual(new Uint8Array([1, 2, 3, 4]));
-    expect(result.toHex()).toEqual('0x0001020304');
-    expect(result.toJSON()).toEqual({
-      ok: 0x04030201
-    });
-  });
-
-  it('decodes from a u8a (error)', (): void => {
-    const result = new Type(registry, new Uint8Array([1, 4 << 2, 100, 101, 102, 103]));
-
-    expect(result.isErr).toBe(true);
-    expect(result.asErr.toU8a()).toEqual(new Uint8Array([4 << 2, 100, 101, 102, 103]));
-    expect(result.toHex()).toEqual('0x011064656667');
-    expect(result.toJSON()).toEqual({
-      err: hexToString('0x64656667')
-    });
-  });
-
-  it('decodes from a JSON representation', (): void => {
-    const result = new Type(registry, { Err: 'error' });
-
-    expect(result.isErr).toBe(true);
-    expect(result.asErr.toString()).toEqual('error');
-    expect(result.toHex()).toEqual('0x01146572726f72');
-  });
-
-  it('decodes reusing instanciated inputs', (): void => {
-    const foo = new Text(registry, 'bar');
-
-    expect(
-      new Result(
-        registry,
-        Text,
-        Text,
-        { Ok: foo }
-      ).asOk
-    ).toBe(foo);
-  });
-
-  it('returns a proper raw typedef rom a built-in', (): void => {
-    expect(registry.createType('DispatchResult').toRawType()).toEqual('Result<(),DispatchError>');
-  });
-});