@pezkuwi/types-codec 16.5.6 → 16.5.8

package/src/base/Null.spec.ts

@@ -0,0 +1,41 @@
+// 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

@@ -0,0 +1,96 @@
+// 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

@@ -0,0 +1,216 @@
+// 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

@@ -0,0 +1,275 @@
+// 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

@@ -0,0 +1,64 @@
+// 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>');
+  });
+});