@metamask/utils 3.1.0 → 3.3.0

package/dist/coercers.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHex = exports.createBytes = exports.createBigInt = exports.createNumber = void 0;
+const superstruct_1 = require("superstruct");
+const hex_1 = require("./hex");
+const assert_1 = require("./assert");
+const bytes_1 = require("./bytes");
+const NumberLikeStruct = (0, superstruct_1.union)([(0, superstruct_1.number)(), (0, superstruct_1.bigint)(), (0, superstruct_1.string)(), hex_1.StrictHexStruct]);
+const NumberCoercer = (0, superstruct_1.coerce)((0, superstruct_1.number)(), NumberLikeStruct, Number);
+const BigIntCoercer = (0, superstruct_1.coerce)((0, superstruct_1.bigint)(), NumberLikeStruct, BigInt);
+const BytesLikeStruct = (0, superstruct_1.union)([hex_1.StrictHexStruct, (0, superstruct_1.instance)(Uint8Array)]);
+const BytesCoercer = (0, superstruct_1.coerce)((0, superstruct_1.instance)(Uint8Array), (0, superstruct_1.union)([hex_1.StrictHexStruct]), bytes_1.hexToBytes);
+const HexCoercer = (0, superstruct_1.coerce)(hex_1.StrictHexStruct, (0, superstruct_1.instance)(Uint8Array), bytes_1.bytesToHex);
+/**
+ * Create a number from a number-like value.
+ *
+ * - If the value is a number, it is returned as-is.
+ * - If the value is a `bigint`, it is converted to a number.
+ * - If the value is a string, it is interpreted as a decimal number.
+ * - If the value is a hex string (i.e., it starts with "0x"), it is
+ * interpreted as a hexadecimal number.
+ *
+ * This validates that the value is a number-like value, and that the resulting
+ * number is not `NaN` or `Infinity`.
+ *
+ * @example
+ * ```typescript
+ * const value = createNumber('0x010203');
+ * console.log(value); // 66051
+ *
+ * const otherValue = createNumber(123n);
+ * console.log(otherValue); // 123
+ * ```
+ * @param value - The value to create the number from.
+ * @returns The created number.
+ * @throws If the value is not a number-like value, or if the resulting number
+ * is `NaN` or `Infinity`.
+ */
+function createNumber(value) {
+    try {
+        const result = (0, superstruct_1.create)(value, NumberCoercer);
+        (0, assert_1.assert)(Number.isFinite(result), `Expected a number-like value, got "${value}".`);
+        return result;
+    }
+    catch (error) {
+        if (error instanceof superstruct_1.StructError) {
+            throw new Error(`Expected a number-like value, got "${value}".`);
+        }
+        /* istanbul ignore next */
+        throw error;
+    }
+}
+exports.createNumber = createNumber;
+/**
+ * Create a `bigint` from a number-like value.
+ *
+ * - If the value is a number, it is converted to a `bigint`.
+ * - If the value is a `bigint`, it is returned as-is.
+ * - If the value is a string, it is interpreted as a decimal number and
+ * converted to a `bigint`.
+ * - If the value is a hex string (i.e., it starts with "0x"), it is
+ * interpreted as a hexadecimal number and converted to a `bigint`.
+ *
+ * @example
+ * ```typescript
+ * const value = createBigInt('0x010203');
+ * console.log(value); // 16909060n
+ *
+ * const otherValue = createBigInt(123);
+ * console.log(otherValue); // 123n
+ * ```
+ * @param value - The value to create the bigint from.
+ * @returns The created bigint.
+ * @throws If the value is not a number-like value.
+ */
+function createBigInt(value) {
+    try {
+        // The `BigInt` constructor throws if the value is not a number-like value.
+        // There is no need to validate the value manually.
+        return (0, superstruct_1.create)(value, BigIntCoercer);
+    }
+    catch (error) {
+        if (error instanceof superstruct_1.StructError) {
+            throw new Error(`Expected a number-like value, got "${error.value}".`);
+        }
+        /* istanbul ignore next */
+        throw error;
+    }
+}
+exports.createBigInt = createBigInt;
+/**
+ * Create a byte array from a bytes-like value.
+ *
+ * - If the value is a byte array, it is returned as-is.
+ * - If the value is a hex string (i.e., it starts with "0x"), it is interpreted
+ * as a hexadecimal number and converted to a byte array.
+ *
+ * @example
+ * ```typescript
+ * const value = createBytes('0x010203');
+ * console.log(value); // Uint8Array [ 1, 2, 3 ]
+ *
+ * const otherValue = createBytes('0x010203');
+ * console.log(otherValue); // Uint8Array [ 1, 2, 3 ]
+ * ```
+ * @param value - The value to create the byte array from.
+ * @returns The created byte array.
+ * @throws If the value is not a bytes-like value.
+ */
+function createBytes(value) {
+    if (typeof value === 'string' && value.toLowerCase() === '0x') {
+        return new Uint8Array();
+    }
+    try {
+        return (0, superstruct_1.create)(value, BytesCoercer);
+    }
+    catch (error) {
+        if (error instanceof superstruct_1.StructError) {
+            throw new Error(`Expected a bytes-like value, got "${error.value}".`);
+        }
+        /* istanbul ignore next */
+        throw error;
+    }
+}
+exports.createBytes = createBytes;
+/**
+ * Create a hexadecimal string from a bytes-like value.
+ *
+ * - If the value is a hex string (i.e., it starts with "0x"), it is returned
+ * as-is.
+ * - If the value is a `Uint8Array`, it is converted to a hex string.
+ *
+ * @example
+ * ```typescript
+ * const value = createHex(new Uint8Array([1, 2, 3]));
+ * console.log(value); // '0x010203'
+ *
+ * const otherValue = createHex('0x010203');
+ * console.log(otherValue); // '0x010203'
+ * ```
+ * @param value - The value to create the hex string from.
+ * @returns The created hex string.
+ * @throws If the value is not a bytes-like value.
+ */
+function createHex(value) {
+    if ((value instanceof Uint8Array && value.length === 0) ||
+        (typeof value === 'string' && value.toLowerCase() === '0x')) {
+        return '0x';
+    }
+    try {
+        return (0, superstruct_1.create)(value, HexCoercer);
+    }
+    catch (error) {
+        if (error instanceof superstruct_1.StructError) {
+            throw new Error(`Expected a bytes-like value, got "${error.value}".`);
+        }
+        /* istanbul ignore next */
+        throw error;
+    }
+}
+exports.createHex = createHex;
+//# sourceMappingURL=coercers.js.map

package/dist/coercers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coercers.js","sourceRoot":"","sources":["../src/coercers.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  bigint,\n  coerce,\n  create,\n  Infer,\n  instance,\n  number,\n  string,\n  StructError,\n  union,\n} from 'superstruct';\nimport { Hex, StrictHexStruct } from './hex';\nimport { assert } from './assert';\nimport { bytesToHex, hexToBytes } from './bytes';\n\nconst NumberLikeStruct = union([number(), bigint(), string(), StrictHexStruct]);\nconst NumberCoercer = coerce(number(), NumberLikeStruct, Number);\nconst BigIntCoercer = coerce(bigint(), NumberLikeStruct, BigInt);\n\nconst BytesLikeStruct = union([StrictHexStruct, instance(Uint8Array)]);\nconst BytesCoercer = coerce(\n  instance(Uint8Array),\n  union([StrictHexStruct]),\n  hexToBytes,\n);\n\nconst HexCoercer = coerce(StrictHexStruct, instance(Uint8Array), bytesToHex);\n\nexport type NumberLike = Infer<typeof NumberLikeStruct>;\nexport type BytesLike = Infer<typeof BytesLikeStruct>;\n\n/**\n * Create a number from a number-like value.\n *\n * - If the value is a number, it is returned as-is.\n * - If the value is a `bigint`, it is converted to a number.\n * - If the value is a string, it is interpreted as a decimal number.\n * - If the value is a hex string (i.e., it starts with \"0x\"), it is\n * interpreted as a hexadecimal number.\n *\n * This validates that the value is a number-like value, and that the resulting\n * number is not `NaN` or `Infinity`.\n *\n * @example\n * ```typescript\n * const value = createNumber('0x010203');\n * console.log(value); // 66051\n *\n * const otherValue = createNumber(123n);\n * console.log(otherValue); // 123\n * ```\n * @param value - The value to create the number from.\n * @returns The created number.\n * @throws If the value is not a number-like value, or if the resulting number\n * is `NaN` or `Infinity`.\n */\nexport function createNumber(value: NumberLike): number {\n  try {\n    const result = create(value, NumberCoercer);\n\n    assert(\n      Number.isFinite(result),\n      `Expected a number-like value, got \"${value}\".`,\n    );\n\n    return result;\n  } catch (error) {\n    if (error instanceof StructError) {\n      throw new Error(`Expected a number-like value, got \"${value}\".`);\n    }\n\n    /* istanbul ignore next */\n    throw error;\n  }\n}\n\n/**\n * Create a `bigint` from a number-like value.\n *\n * - If the value is a number, it is converted to a `bigint`.\n * - If the value is a `bigint`, it is returned as-is.\n * - If the value is a string, it is interpreted as a decimal number and\n * converted to a `bigint`.\n * - If the value is a hex string (i.e., it starts with \"0x\"), it is\n * interpreted as a hexadecimal number and converted to a `bigint`.\n *\n * @example\n * ```typescript\n * const value = createBigInt('0x010203');\n * console.log(value); // 16909060n\n *\n * const otherValue = createBigInt(123);\n * console.log(otherValue); // 123n\n * ```\n * @param value - The value to create the bigint from.\n * @returns The created bigint.\n * @throws If the value is not a number-like value.\n */\nexport function createBigInt(value: NumberLike): bigint {\n  try {\n    // The `BigInt` constructor throws if the value is not a number-like value.\n    // There is no need to validate the value manually.\n    return create(value, BigIntCoercer);\n  } catch (error) {\n    if (error instanceof StructError) {\n      throw new Error(`Expected a number-like value, got \"${error.value}\".`);\n    }\n\n    /* istanbul ignore next */\n    throw error;\n  }\n}\n\n/**\n * Create a byte array from a bytes-like value.\n *\n * - If the value is a byte array, it is returned as-is.\n * - If the value is a hex string (i.e., it starts with \"0x\"), it is interpreted\n * as a hexadecimal number and converted to a byte array.\n *\n * @example\n * ```typescript\n * const value = createBytes('0x010203');\n * console.log(value); // Uint8Array [ 1, 2, 3 ]\n *\n * const otherValue = createBytes('0x010203');\n * console.log(otherValue); // Uint8Array [ 1, 2, 3 ]\n * ```\n * @param value - The value to create the byte array from.\n * @returns The created byte array.\n * @throws If the value is not a bytes-like value.\n */\nexport function createBytes(value: BytesLike): Uint8Array {\n  if (typeof value === 'string' && value.toLowerCase() === '0x') {\n    return new Uint8Array();\n  }\n\n  try {\n    return create(value, BytesCoercer);\n  } catch (error) {\n    if (error instanceof StructError) {\n      throw new Error(`Expected a bytes-like value, got \"${error.value}\".`);\n    }\n\n    /* istanbul ignore next */\n    throw error;\n  }\n}\n\n/**\n * Create a hexadecimal string from a bytes-like value.\n *\n * - If the value is a hex string (i.e., it starts with \"0x\"), it is returned\n * as-is.\n * - If the value is a `Uint8Array`, it is converted to a hex string.\n *\n * @example\n * ```typescript\n * const value = createHex(new Uint8Array([1, 2, 3]));\n * console.log(value); // '0x010203'\n *\n * const otherValue = createHex('0x010203');\n * console.log(otherValue); // '0x010203'\n * ```\n * @param value - The value to create the hex string from.\n * @returns The created hex string.\n * @throws If the value is not a bytes-like value.\n */\nexport function createHex(value: BytesLike): Hex {\n  if (\n    (value instanceof Uint8Array && value.length === 0) ||\n    (typeof value === 'string' && value.toLowerCase() === '0x')\n  ) {\n    return '0x';\n  }\n\n  try {\n    return create(value, HexCoercer);\n  } catch (error) {\n    if (error instanceof StructError) {\n      throw new Error(`Expected a bytes-like value, got \"${error.value}\".`);\n    }\n\n    /* istanbul ignore next */\n    throw error;\n  }\n}\n"]}

package/dist/hex.d.ts

@@ -1,3 +1,7 @@
+import { Struct } from 'superstruct';
+export declare type Hex = `0x${string}`;
+export declare const HexStruct: Struct<string, null>;
+export declare const StrictHexStruct: Struct<`0x${string}`, null>;
 /**
  * Check if a string is a valid hex string.
  *
@@ -5,6 +9,14 @@
  * @returns Whether the value is a valid hex string.
  */
 export declare function isHexString(value: unknown): value is string;
+/**
+ * Strictly check if a string is a valid hex string. A valid hex string must
+ * start with the "0x"-prefix.
+ *
+ * @param value - The value to check.
+ * @returns Whether the value is a valid hex string.
+ */
+export declare function isStrictHexString(value: unknown): value is Hex;
 /**
  * Assert that a value is a valid hex string.
  *
@@ -12,6 +24,14 @@ export declare function isHexString(value: unknown): value is string;
  * @throws If the value is not a valid hex string.
  */
 export declare function assertIsHexString(value: unknown): asserts value is string;
+/**
+ * Assert that a value is a valid hex string. A valid hex string must start with
+ * the "0x"-prefix.
+ *
+ * @param value - The value to check.
+ * @throws If the value is not a valid hex string.
+ */
+export declare function assertIsStrictHexString(value: unknown): asserts value is Hex;
 /**
  * Add the `0x`-prefix to a hexadecimal string. If the string already has the
  * prefix, it is returned as-is.
@@ -19,7 +39,7 @@ export declare function assertIsHexString(value: unknown): asserts value is stri
  * @param hex - The hexadecimal string to add the prefix to.
  * @returns The prefixed hexadecimal string.
  */
-export declare function add0x(hex: string): string;
+export declare function add0x(hex: string): Hex;
 /**
  * Remove the `0x`-prefix from a hexadecimal string. If the string doesn't have
  * the prefix, it is returned as-is.

package/dist/hex.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.remove0x = exports.add0x = exports.assertIsHexString = exports.isHexString = void 0;
+exports.remove0x = exports.add0x = exports.assertIsStrictHexString = exports.assertIsHexString = exports.isStrictHexString = exports.isHexString = exports.StrictHexStruct = exports.HexStruct = void 0;
 const superstruct_1 = require("superstruct");
 const assert_1 = require("./assert");
-const HexStruct = (0, superstruct_1.pattern)((0, superstruct_1.string)(), /^(?:0x)?[0-9a-f]+$/iu);
+exports.HexStruct = (0, superstruct_1.pattern)((0, superstruct_1.string)(), /^(?:0x)?[0-9a-f]+$/iu);
+exports.StrictHexStruct = (0, superstruct_1.pattern)((0, superstruct_1.string)(), /^0x[0-9a-f]+$/iu);
 /**
  * Check if a string is a valid hex string.
  *
@@ -11,9 +12,20 @@ const HexStruct = (0, superstruct_1.pattern)((0, superstruct_1.string)(), /^(?:0
  * @returns Whether the value is a valid hex string.
  */
 function isHexString(value) {
-    return (0, superstruct_1.is)(value, HexStruct);
+    return (0, superstruct_1.is)(value, exports.HexStruct);
 }
 exports.isHexString = isHexString;
+/**
+ * Strictly check if a string is a valid hex string. A valid hex string must
+ * start with the "0x"-prefix.
+ *
+ * @param value - The value to check.
+ * @returns Whether the value is a valid hex string.
+ */
+function isStrictHexString(value) {
+    return (0, superstruct_1.is)(value, exports.StrictHexStruct);
+}
+exports.isStrictHexString = isStrictHexString;
 /**
  * Assert that a value is a valid hex string.
  *
@@ -24,6 +36,17 @@ function assertIsHexString(value) {
     (0, assert_1.assert)(isHexString(value), 'Value must be a hexadecimal string.');
 }
 exports.assertIsHexString = assertIsHexString;
+/**
+ * Assert that a value is a valid hex string. A valid hex string must start with
+ * the "0x"-prefix.
+ *
+ * @param value - The value to check.
+ * @throws If the value is not a valid hex string.
+ */
+function assertIsStrictHexString(value) {
+    (0, assert_1.assert)(isStrictHexString(value), 'Value must be a hexadecimal string, starting with "0x".');
+}
+exports.assertIsStrictHexString = assertIsStrictHexString;
 /**
  * Add the `0x`-prefix to a hexadecimal string. If the string already has the
  * prefix, it is returned as-is.
@@ -32,9 +55,12 @@ exports.assertIsHexString = assertIsHexString;
  * @returns The prefixed hexadecimal string.
  */
 function add0x(hex) {
-    if (hex.startsWith('0x') || hex.startsWith('0X')) {
+    if (hex.startsWith('0x')) {
         return hex;
     }
+    if (hex.startsWith('0X')) {
+        return `0x${hex.substring(2)}`;
+    }
     return `0x${hex}`;
 }
 exports.add0x = add0x;

package/dist/hex.js.map

@@ -1 +1 @@
-{"version":3,"file":"hex.js","sourceRoot":"","sources":["../src/hex.ts"],"names":[],"mappings":";;;AAAA,6CAAkD;AAClD,qCAAkC;AAElC,MAAM,SAAS,GAAG,IAAA,qBAAO,EAAC,IAAA,oBAAM,GAAE,EAAE,sBAAsB,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,SAAgB,WAAW,CAAC,KAAc;IACxC,OAAO,IAAA,gBAAE,EAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AAC9B,CAAC;AAFD,kCAEC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,KAAc;IAC9C,IAAA,eAAM,EAAC,WAAW,CAAC,KAAK,CAAC,EAAE,qCAAqC,CAAC,CAAC;AACpE,CAAC;AAFD,8CAEC;AAED;;;;;;GAMG;AACH,SAAgB,KAAK,CAAC,GAAW;IAC/B,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE;QAChD,OAAO,GAAG,CAAC;KACZ;IAED,OAAO,KAAK,GAAG,EAAE,CAAC;AACpB,CAAC;AAND,sBAMC;AAED;;;;;;GAMG;AACH,SAAgB,QAAQ,CAAC,GAAW;IAClC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE;QAChD,OAAO,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;KACzB;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAND,4BAMC","sourcesContent":["import { is, pattern, string } from 'superstruct';\nimport { assert } from './assert';\n\nconst HexStruct = pattern(string(), /^(?:0x)?[0-9a-f]+$/iu);\n\n/**\n * Check if a string is a valid hex string.\n *\n * @param value - The value to check.\n * @returns Whether the value is a valid hex string.\n */\nexport function isHexString(value: unknown): value is string {\n  return is(value, HexStruct);\n}\n\n/**\n * Assert that a value is a valid hex string.\n *\n * @param value - The value to check.\n * @throws If the value is not a valid hex string.\n */\nexport function assertIsHexString(value: unknown): asserts value is string {\n  assert(isHexString(value), 'Value must be a hexadecimal string.');\n}\n\n/**\n * Add the `0x`-prefix to a hexadecimal string. If the string already has the\n * prefix, it is returned as-is.\n *\n * @param hex - The hexadecimal string to add the prefix to.\n * @returns The prefixed hexadecimal string.\n */\nexport function add0x(hex: string): string {\n  if (hex.startsWith('0x') || hex.startsWith('0X')) {\n    return hex;\n  }\n\n  return `0x${hex}`;\n}\n\n/**\n * Remove the `0x`-prefix from a hexadecimal string. If the string doesn't have\n * the prefix, it is returned as-is.\n *\n * @param hex - The hexadecimal string to remove the prefix from.\n * @returns The un-prefixed hexadecimal string.\n */\nexport function remove0x(hex: string): string {\n  if (hex.startsWith('0x') || hex.startsWith('0X')) {\n    return hex.substring(2);\n  }\n\n  return hex;\n}\n"]}
+{"version":3,"file":"hex.js","sourceRoot":"","sources":["../src/hex.ts"],"names":[],"mappings":";;;AAAA,6CAA0D;AAC1D,qCAAkC;AAIrB,QAAA,SAAS,GAAG,IAAA,qBAAO,EAAC,IAAA,oBAAM,GAAE,EAAE,sBAAsB,CAAC,CAAC;AACtD,QAAA,eAAe,GAAG,IAAA,qBAAO,EAAC,IAAA,oBAAM,GAAE,EAAE,iBAAiB,CAGjE,CAAC;AAEF;;;;;GAKG;AACH,SAAgB,WAAW,CAAC,KAAc;IACxC,OAAO,IAAA,gBAAE,EAAC,KAAK,EAAE,iBAAS,CAAC,CAAC;AAC9B,CAAC;AAFD,kCAEC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,KAAc;IAC9C,OAAO,IAAA,gBAAE,EAAC,KAAK,EAAE,uBAAe,CAAC,CAAC;AACpC,CAAC;AAFD,8CAEC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,KAAc;IAC9C,IAAA,eAAM,EAAC,WAAW,CAAC,KAAK,CAAC,EAAE,qCAAqC,CAAC,CAAC;AACpE,CAAC;AAFD,8CAEC;AAED;;;;;;GAMG;AACH,SAAgB,uBAAuB,CAAC,KAAc;IACpD,IAAA,eAAM,EACJ,iBAAiB,CAAC,KAAK,CAAC,EACxB,yDAAyD,CAC1D,CAAC;AACJ,CAAC;AALD,0DAKC;AAED;;;;;;GAMG;AACH,SAAgB,KAAK,CAAC,GAAW;IAC/B,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE;QACxB,OAAO,GAAU,CAAC;KACnB;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE;QACxB,OAAO,KAAK,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;KAChC;IAED,OAAO,KAAK,GAAG,EAAE,CAAC;AACpB,CAAC;AAVD,sBAUC;AAED;;;;;;GAMG;AACH,SAAgB,QAAQ,CAAC,GAAW;IAClC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE;QAChD,OAAO,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;KACzB;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAND,4BAMC","sourcesContent":["import { is, pattern, string, Struct } from 'superstruct';\nimport { assert } from './assert';\n\nexport type Hex = `0x${string}`;\n\nexport const HexStruct = pattern(string(), /^(?:0x)?[0-9a-f]+$/iu);\nexport const StrictHexStruct = pattern(string(), /^0x[0-9a-f]+$/iu) as Struct<\n  Hex,\n  null\n>;\n\n/**\n * Check if a string is a valid hex string.\n *\n * @param value - The value to check.\n * @returns Whether the value is a valid hex string.\n */\nexport function isHexString(value: unknown): value is string {\n  return is(value, HexStruct);\n}\n\n/**\n * Strictly check if a string is a valid hex string. A valid hex string must\n * start with the \"0x\"-prefix.\n *\n * @param value - The value to check.\n * @returns Whether the value is a valid hex string.\n */\nexport function isStrictHexString(value: unknown): value is Hex {\n  return is(value, StrictHexStruct);\n}\n\n/**\n * Assert that a value is a valid hex string.\n *\n * @param value - The value to check.\n * @throws If the value is not a valid hex string.\n */\nexport function assertIsHexString(value: unknown): asserts value is string {\n  assert(isHexString(value), 'Value must be a hexadecimal string.');\n}\n\n/**\n * Assert that a value is a valid hex string. A valid hex string must start with\n * the \"0x\"-prefix.\n *\n * @param value - The value to check.\n * @throws If the value is not a valid hex string.\n */\nexport function assertIsStrictHexString(value: unknown): asserts value is Hex {\n  assert(\n    isStrictHexString(value),\n    'Value must be a hexadecimal string, starting with \"0x\".',\n  );\n}\n\n/**\n * Add the `0x`-prefix to a hexadecimal string. If the string already has the\n * prefix, it is returned as-is.\n *\n * @param hex - The hexadecimal string to add the prefix to.\n * @returns The prefixed hexadecimal string.\n */\nexport function add0x(hex: string): Hex {\n  if (hex.startsWith('0x')) {\n    return hex as Hex;\n  }\n\n  if (hex.startsWith('0X')) {\n    return `0x${hex.substring(2)}`;\n  }\n\n  return `0x${hex}`;\n}\n\n/**\n * Remove the `0x`-prefix from a hexadecimal string. If the string doesn't have\n * the prefix, it is returned as-is.\n *\n * @param hex - The hexadecimal string to remove the prefix from.\n * @returns The un-prefixed hexadecimal string.\n */\nexport function remove0x(hex: string): string {\n  if (hex.startsWith('0x') || hex.startsWith('0X')) {\n    return hex.substring(2);\n  }\n\n  return hex;\n}\n"]}

package/dist/hex.test-d.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hex.test-d.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tsd_1 = require("tsd");
+// Valid hex strings:
+(0, tsd_1.expectAssignable)('0x');
+(0, tsd_1.expectAssignable)('0x0');
+(0, tsd_1.expectAssignable)('0x😀');
+const embeddedString = 'test';
+(0, tsd_1.expectAssignable)(`0x${embeddedString}`);
+// Not valid hex strings:
+(0, tsd_1.expectNotAssignable)(`0X${embeddedString}`);
+(0, tsd_1.expectNotAssignable)(`1x${embeddedString}`);
+(0, tsd_1.expectNotAssignable)(0);
+(0, tsd_1.expectNotAssignable)('0');
+(0, tsd_1.expectNotAssignable)('🙃');
+//# sourceMappingURL=hex.test-d.js.map

package/dist/hex.test-d.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hex.test-d.js","sourceRoot":"","sources":["../src/hex.test-d.ts"],"names":[],"mappings":";;AAAA,6BAA4D;AAI5D,qBAAqB;AAErB,IAAA,sBAAgB,EAAM,IAAI,CAAC,CAAC;AAE5B,IAAA,sBAAgB,EAAM,KAAK,CAAC,CAAC;AAE7B,IAAA,sBAAgB,EAAM,MAAM,CAAC,CAAC;AAE9B,MAAM,cAAc,GAAG,MAAM,CAAC;AAC9B,IAAA,sBAAgB,EAAM,KAAK,cAAc,EAAE,CAAC,CAAC;AAE7C,yBAAyB;AAEzB,IAAA,yBAAmB,EAAM,KAAK,cAAc,EAAE,CAAC,CAAC;AAEhD,IAAA,yBAAmB,EAAM,KAAK,cAAc,EAAE,CAAC,CAAC;AAEhD,IAAA,yBAAmB,EAAM,CAAC,CAAC,CAAC;AAE5B,IAAA,yBAAmB,EAAM,GAAG,CAAC,CAAC;AAE9B,IAAA,yBAAmB,EAAM,IAAI,CAAC,CAAC","sourcesContent":["import { expectAssignable, expectNotAssignable } from 'tsd';\n\nimport { Hex } from '.';\n\n// Valid hex strings:\n\nexpectAssignable<Hex>('0x');\n\nexpectAssignable<Hex>('0x0');\n\nexpectAssignable<Hex>('0x😀');\n\nconst embeddedString = 'test';\nexpectAssignable<Hex>(`0x${embeddedString}`);\n\n// Not valid hex strings:\n\nexpectNotAssignable<Hex>(`0X${embeddedString}`);\n\nexpectNotAssignable<Hex>(`1x${embeddedString}`);\n\nexpectNotAssignable<Hex>(0);\n\nexpectNotAssignable<Hex>('0');\n\nexpectNotAssignable<Hex>('🙃');\n"]}

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export * from './assert';
 export * from './bytes';
+export * from './coercers';
 export * from './collections';
 export * from './hex';
 export * from './json';
 export * from './logging';
 export * from './misc';
+export * from './number';
 export * from './time';

package/dist/index.js

@@ -16,10 +16,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./assert"), exports);
 __exportStar(require("./bytes"), exports);
+__exportStar(require("./coercers"), exports);
 __exportStar(require("./collections"), exports);
 __exportStar(require("./hex"), exports);
 __exportStar(require("./json"), exports);
 __exportStar(require("./logging"), exports);
 __exportStar(require("./misc"), exports);
+__exportStar(require("./number"), exports);
 __exportStar(require("./time"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,0CAAwB;AACxB,gDAA8B;AAC9B,wCAAsB;AACtB,yCAAuB;AACvB,4CAA0B;AAC1B,yCAAuB;AACvB,yCAAuB","sourcesContent":["export * from './assert';\nexport * from './bytes';\nexport * from './collections';\nexport * from './hex';\nexport * from './json';\nexport * from './logging';\nexport * from './misc';\nexport * from './time';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,0CAAwB;AACxB,6CAA2B;AAC3B,gDAA8B;AAC9B,wCAAsB;AACtB,yCAAuB;AACvB,4CAA0B;AAC1B,yCAAuB;AACvB,2CAAyB;AACzB,yCAAuB","sourcesContent":["export * from './assert';\nexport * from './bytes';\nexport * from './coercers';\nexport * from './collections';\nexport * from './hex';\nexport * from './json';\nexport * from './logging';\nexport * from './misc';\nexport * from './number';\nexport * from './time';\n"]}

package/dist/json.d.ts

@@ -1,5 +1,6 @@
 import { Infer, Struct } from 'superstruct';
-export declare const JsonStruct: Struct<Json>;
+import { AssertionErrorConstructor } from './assert';
+export declare const JsonStruct: Struct<Json, null>;
 /**
  * Any JSON-compatible value.
  */
@@ -7,10 +8,11 @@ export declare type Json = null | boolean | number | string | Json[] | {
     [prop: string]: Json;
 };
 /**
- * Type guard for {@link Json}.
+ * Check if the given value is a valid {@link Json} value, i.e., a value that is
+ * serializable to JSON.
  *
  * @param value - The value to check.
- * @returns Whether the value is valid JSON.
+ * @returns Whether the value is a valid {@link Json} value.
  */
 export declare function isValidJson(value: unknown): value is Json;
 /**
@@ -33,13 +35,13 @@ export declare const JsonRpcIdStruct: Struct<string | number | null, null>;
 export declare type JsonRpcId = Infer<typeof JsonRpcIdStruct>;
 export declare const JsonRpcErrorStruct: Struct<{
     code: number;
-    data: unknown;
     message: string;
+    data?: Json | undefined;
     stack?: string | undefined;
 }, {
     code: Struct<number, null>;
     message: Struct<string, null>;
-    data: Struct<unknown, null>;
+    data: Struct<Json | undefined, null>;
     stack: Struct<string | undefined, null>;
 }>;
 /**
@@ -91,34 +93,70 @@ export declare const JsonRpcNotificationStruct: Struct<{
  */
 export declare type JsonRpcNotification<Params extends JsonRpcParams> = InferWithParams<typeof JsonRpcNotificationStruct, Params>;
 /**
- * Type guard to narrow a JSON-RPC request or notification object to a
- * notification.
+ * Check if the given value is a valid {@link JsonRpcNotification} object.
  *
- * @param requestOrNotification - The JSON-RPC request or notification to check.
- * @returns Whether the specified JSON-RPC message is a notification.
+ * @param value - The value to check.
+ * @returns Whether the given value is a valid {@link JsonRpcNotification}
+ * object.
  */
-export declare function isJsonRpcNotification(requestOrNotification: unknown): requestOrNotification is JsonRpcNotification<JsonRpcParams>;
+export declare function isJsonRpcNotification(value: unknown): value is JsonRpcNotification<JsonRpcParams>;
 /**
- * Assertion type guard to narrow a JSON-RPC request or notification object to a
- * notification.
+ * Assert that the given value is a valid {@link JsonRpcNotification} object.
  *
- * @param requestOrNotification - The JSON-RPC request or notification to check.
+ * @param value - The value to check.
+ * @param ErrorWrapper - The error class to throw if the assertion fails.
+ * Defaults to {@link AssertionError}.
+ * @throws If the given value is not a valid {@link JsonRpcNotification} object.
  */
-export declare function assertIsJsonRpcNotification(requestOrNotification: unknown): asserts requestOrNotification is JsonRpcNotification<JsonRpcParams>;
+export declare function assertIsJsonRpcNotification(value: unknown, ErrorWrapper?: AssertionErrorConstructor): asserts value is JsonRpcNotification<JsonRpcParams>;
 /**
- * Type guard to narrow a JSON-RPC request or notification object to a request.
+ * Check if the given value is a valid {@link JsonRpcRequest} object.
  *
- * @param requestOrNotification - The JSON-RPC request or notification to check.
- * @returns Whether the specified JSON-RPC message is a request.
+ * @param value - The value to check.
+ * @returns Whether the given value is a valid {@link JsonRpcRequest} object.
  */
-export declare function isJsonRpcRequest(requestOrNotification: unknown): requestOrNotification is JsonRpcRequest<JsonRpcParams>;
+export declare function isJsonRpcRequest(value: unknown): value is JsonRpcRequest<JsonRpcParams>;
 /**
- * Assertion type guard to narrow a JSON-RPC request or notification object to a
- * request.
+ * Assert that the given value is a valid {@link JsonRpcRequest} object.
  *
- * @param requestOrNotification - The JSON-RPC request or notification to check.
+ * @param value - The JSON-RPC request or notification to check.
+ * @param ErrorWrapper - The error class to throw if the assertion fails.
+ * Defaults to {@link AssertionError}.
+ * @throws If the given value is not a valid {@link JsonRpcRequest} object.
+ */
+export declare function assertIsJsonRpcRequest(value: unknown, ErrorWrapper?: AssertionErrorConstructor): asserts value is JsonRpcRequest<JsonRpcParams>;
+export declare const PendingJsonRpcResponseStruct: Struct<{
+    id: string | number | null;
+    jsonrpc: "2.0";
+    result: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: Json | undefined;
+        stack?: string | undefined;
+    } | undefined;
+}, {
+    id: Struct<string | number | null, null>;
+    jsonrpc: Struct<"2.0", "2.0">;
+    result: Struct<unknown, null>;
+    error: Struct<{
+        code: number;
+        message: string;
+        data?: Json | undefined;
+        stack?: string | undefined;
+    } | undefined, {
+        code: Struct<number, null>;
+        message: Struct<string, null>;
+        data: Struct<Json | undefined, null>;
+        stack: Struct<string | undefined, null>;
+    }>;
+}>;
+/**
+ * A JSON-RPC response object that has not yet been resolved.
  */
-export declare function assertIsJsonRpcRequest(requestOrNotification: unknown): asserts requestOrNotification is JsonRpcRequest<JsonRpcParams>;
+export declare type PendingJsonRpcResponse<Result extends Json> = Omit<Infer<typeof PendingJsonRpcResponseStruct>, 'result'> & {
+    result?: Result;
+};
 export declare const JsonRpcSuccessStruct: Struct<{
     id: string | number | null;
     jsonrpc: "2.0";
@@ -126,7 +164,7 @@ export declare const JsonRpcSuccessStruct: Struct<{
 }, {
     id: Struct<string | number | null, null>;
     jsonrpc: Struct<"2.0", "2.0">;
-    result: Struct<Json, unknown>;
+    result: Struct<Json, null>;
 }>;
 /**
  * A successful JSON-RPC response object.
@@ -164,45 +202,87 @@ export declare const JsonRpcResponseStruct: Struct<{
  */
 export declare type JsonRpcResponse<Result extends Json> = JsonRpcSuccess<Result> | JsonRpcFailure;
 /**
- * Type guard to check if a value is a JsonRpcResponse.
+ * Type guard to check whether specified JSON-RPC response is a
+ * {@link PendingJsonRpcResponse}.
+ *
+ * @param response - The JSON-RPC response to check.
+ * @returns Whether the specified JSON-RPC response is pending.
+ */
+export declare function isPendingJsonRpcResponse(response: unknown): response is PendingJsonRpcResponse<Json>;
+/**
+ * Assert that the given value is a valid {@link PendingJsonRpcResponse} object.
+ *
+ * @param response - The JSON-RPC response to check.
+ * @param ErrorWrapper - The error class to throw if the assertion fails.
+ * Defaults to {@link AssertionError}.
+ * @throws If the given value is not a valid {@link PendingJsonRpcResponse}
+ * object.
+ */
+export declare function assertIsPendingJsonRpcResponse(response: unknown, ErrorWrapper?: AssertionErrorConstructor): asserts response is PendingJsonRpcResponse<Json>;
+/**
+ * Type guard to check if a value is a {@link JsonRpcResponse}.
  *
  * @param response - The object to check.
  * @returns Whether the object is a JsonRpcResponse.
  */
 export declare function isJsonRpcResponse(response: unknown): response is JsonRpcResponse<Json>;
 /**
- * Type assertion to check if a value is a JsonRpcResponse.
+ * Assert that the given value is a valid {@link JsonRpcResponse} object.
  *
- * @param response - The response to check.
+ * @param value - The value to check.
+ * @param ErrorWrapper - The error class to throw if the assertion fails.
+ * Defaults to {@link AssertionError}.
+ * @throws If the given value is not a valid {@link JsonRpcResponse} object.
  */
-export declare function assertIsJsonRpcResponse(response: unknown): asserts response is JsonRpcResponse<Json>;
+export declare function assertIsJsonRpcResponse(value: unknown, ErrorWrapper?: AssertionErrorConstructor): asserts value is JsonRpcResponse<Json>;
 /**
- * Type guard to narrow a JsonRpcResponse object to a success (or failure).
+ * Check if the given value is a valid {@link JsonRpcSuccess} object.
  *
- * @param response - The response object to check.
- * @returns Whether the response object is a success.
+ * @param value - The value to check.
+ * @returns Whether the given value is a valid {@link JsonRpcSuccess} object.
  */
-export declare function isJsonRpcSuccess(response: unknown): response is JsonRpcSuccess<Json>;
+export declare function isJsonRpcSuccess(value: unknown): value is JsonRpcSuccess<Json>;
 /**
- * Type assertion to narrow a JsonRpcResponse object to a success (or failure).
+ * Assert that the given value is a valid {@link JsonRpcSuccess} object.
  *
- * @param response - The response object to check.
+ * @param value - The value to check.
+ * @param ErrorWrapper - The error class to throw if the assertion fails.
+ * Defaults to {@link AssertionError}.
+ * @throws If the given value is not a valid {@link JsonRpcSuccess} object.
  */
-export declare function assertIsJsonRpcSuccess(response: unknown): asserts response is JsonRpcSuccess<Json>;
+export declare function assertIsJsonRpcSuccess(value: unknown, ErrorWrapper?: AssertionErrorConstructor): asserts value is JsonRpcSuccess<Json>;
 /**
- * Type guard to narrow a JsonRpcResponse object to a failure (or success).
+ * Check if the given value is a valid {@link JsonRpcFailure} object.
  *
- * @param response - The response object to check.
- * @returns Whether the response object is a failure, i.e. has an `error`
- * property.
+ * @param value - The value to check.
+ * @returns Whether the given value is a valid {@link JsonRpcFailure} object.
  */
-export declare function isJsonRpcFailure(response: unknown): response is JsonRpcFailure;
+export declare function isJsonRpcFailure(value: unknown): value is JsonRpcFailure;
 /**
- * Type assertion to narrow a JsonRpcResponse object to a failure (or success).
+ * Assert that the given value is a valid {@link JsonRpcFailure} object.
  *
- * @param response - The response object to check.
+ * @param value - The value to check.
+ * @param ErrorWrapper - The error class to throw if the assertion fails.
+ * Defaults to {@link AssertionError}.
+ * @throws If the given value is not a valid {@link JsonRpcFailure} object.
+ */
+export declare function assertIsJsonRpcFailure(value: unknown, ErrorWrapper?: AssertionErrorConstructor): asserts value is JsonRpcFailure;
+/**
+ * Check if the given value is a valid {@link JsonRpcError} object.
+ *
+ * @param value - The value to check.
+ * @returns Whether the given value is a valid {@link JsonRpcError} object.
+ */
+export declare function isJsonRpcError(value: unknown): value is JsonRpcError;
+/**
+ * Assert that the given value is a valid {@link JsonRpcError} object.
+ *
+ * @param value - The value to check.
+ * @param ErrorWrapper - The error class to throw if the assertion fails.
+ * Defaults to {@link AssertionError}.
+ * @throws If the given value is not a valid {@link JsonRpcError} object.
  */
-export declare function assertIsJsonRpcFailure(response: unknown): asserts response is JsonRpcFailure;
+export declare function assertIsJsonRpcError(value: unknown, ErrorWrapper?: AssertionErrorConstructor): asserts value is JsonRpcError;
 declare type JsonRpcValidatorOptions = {
     permitEmptyString?: boolean;
     permitFractions?: boolean;