@xylabs/hex
Advanced tools
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
Using npm:
npm install {{name}}
Using yarn:
yarn add {{name}}
Using pnpm:
pnpm add {{name}}
Using bun:
bun add {{name}}
See the LICENSE file for license rights and limitations (LGPL-3.0-only).
### .temp-typedoc
### functions
### <a id="HexRegExMinMax"></a>HexRegExMinMax
function HexRegExMinMax(minBytes?, maxBytes?): RegExp;
Creates a RegExp matching lowercase hex strings with a byte length in the given range.
number = 0
Minimum number of bytes (default 0)
number = ...
Maximum number of bytes
RegExp
A RegExp for validating hex strings within the byte range
### <a id="HexRegExMinMaxMixedCaseWithPrefix"></a>HexRegExMinMaxMixedCaseWithPrefix
function HexRegExMinMaxMixedCaseWithPrefix(minBytes?, maxBytes?): RegExp;
Creates a RegExp matching mixed-case hex strings with a 0x prefix and a byte length in the given range.
number = 0
Minimum number of bytes (default 0)
number = ...
Maximum number of bytes
RegExp
A RegExp for validating prefixed hex strings within the byte range
### <a id="asAddress"></a>asAddress
function asAddress(value?): BrandedAddress | undefined;
Attempts to coerce a value into an Address type, returning undefined or throwing based on the assert config.
unknown
The value to coerce (must be a string)
BrandedAddress | undefined
The value as Address, or undefined if coercion fails and assert is not set
function asAddress(value, assert): BrandedAddress;
Attempts to coerce a value into an Address type, returning undefined or throwing based on the assert config.
unknown
The value to coerce (must be a string)
AssertConfig
If provided, throws on failure instead of returning undefined
BrandedAddress
The value as Address, or undefined if coercion fails and assert is not set
### <a id="asAddressV2"></a>asAddressV2
function asAddressV2(value?, assert?): BrandedAddress | undefined;
Alpha
unknown
boolean = false
BrandedAddress | undefined
### <a id="asEthAddress"></a>asEthAddress
function asEthAddress(value): EthAddress | undefined;
Attempts to coerce a value into an EthAddress, returning undefined or throwing based on the assert config.
unknown
The value to coerce (must be a string)
EthAddress | undefined
The value as EthAddress, or undefined if coercion fails and assert is not set
function asEthAddress(value, assert): EthAddress;
Attempts to coerce a value into an EthAddress, returning undefined or throwing based on the assert config.
unknown
The value to coerce (must be a string)
AssertConfig
If provided, throws on failure instead of returning undefined
The value as EthAddress, or undefined if coercion fails and assert is not set
### <a id="asHash"></a>asHash
function asHash(value): BrandedHash | undefined;
Attempts to coerce a value into a Hash type, returning undefined or throwing based on the assert config.
unknown
The value to coerce (must be a string)
BrandedHash | undefined
The value as Hash, or undefined if coercion fails and assert is not set
function asHash(value, assert): BrandedHash;
Attempts to coerce a value into a Hash type, returning undefined or throwing based on the assert config.
unknown
The value to coerce (must be a string)
AssertConfig
If provided, throws on failure instead of returning undefined
The value as Hash, or undefined if coercion fails and assert is not set
### <a id="asHex"></a>asHex
function asHex(value): BrandedHex | undefined;
Attempts to coerce a value into a Hex type, returning undefined or throwing based on the assert config.
unknown
The value to coerce (must be a string)
BrandedHex | undefined
The value as Hex, or undefined if coercion fails and assert is not set
function asHex(value, assert): BrandedHex;
Attempts to coerce a value into a Hex type, returning undefined or throwing based on the assert config.
unknown
The value to coerce (must be a string)
AssertConfig
If provided, throws on failure instead of returning undefined
The value as Hex, or undefined if coercion fails and assert is not set
### <a id="bitsToNibbles"></a>bitsToNibbles
function bitsToNibbles(value): number;
Converts a bit count to the equivalent number of hex nibbles (4 bits each).
number
The number of bits (must be a multiple of 4)
number
The number of nibbles
### <a id="hexFrom"></a>hexFrom
function hexFrom(value, config?): BrandedHex;
Takes unknown value and tries our best to convert it to a hex string
string | number | bigint | ArrayBufferLike
Supported types are string, number, bigint, and ArrayBuffer
Configuration of output format and validation
### <a id="hexFromArrayBuffer"></a>hexFromArrayBuffer
function hexFromArrayBuffer(buffer, config?): BrandedHex;
Convert an ArrayBuffer to a hex string
ArrayBufferLike
The buffer to be converted
Configuration of output format and validation
### <a id="hexFromBigInt"></a>hexFromBigInt
function hexFromBigInt(value, config?): BrandedHex;
Convert a bigint to a hex string
bigint
The bigint to be converted
HexConfig = {}
Configuration of output format and validation
### <a id="hexFromHexString"></a>hexFromHexString
function hexFromHexString(value, config?): BrandedHex;
Normalizes a hex string by stripping an optional 0x prefix, lowercasing, and padding to byte/bit boundaries.
string
The hex string to normalize (with or without 0x prefix)
HexConfig = {}
Configuration for prefix, byteSize, and bitLength padding
The normalized Hex string
### <a id="hexFromNumber"></a>hexFromNumber
function hexFromNumber(value, config?): BrandedHex;
Converts a number to a hex string by converting to BigInt first.
number
The number to convert
Optional hex output configuration
The hex string representation
### <a id="hexToBigInt"></a>hexToBigInt
function hexToBigInt(hex): bigint;
Converts a Hex string to a BigInt.
The hex string to convert
bigint
The BigInt representation of the hex value
### <a id="isAddress"></a>isAddress
function isAddress(value?, config?): value is BrandedAddress;
Type guard that checks whether a value is a valid 160-bit address.
unknown
The value to check
HexConfig = {}
Optional hex config (defaults to 160-bit, no prefix)
value is BrandedAddress
True if the value is a valid Address
### <a id="isAddressV2"></a>isAddressV2
function isAddressV2(value?): value is BrandedAddress;
Alpha
unknown
value is BrandedAddress
### <a id="isEthAddress"></a>isEthAddress
function isEthAddress(value?, config?): value is EthAddress;
Type guard that checks whether a value is a valid 0x-prefixed Ethereum address.
unknown
The value to check
HexConfig = {}
Optional hex config (defaults to 160-bit with prefix)
value is EthAddress
True if the value is a valid EthAddress
### <a id="isHash"></a>isHash
function isHash(value, bitLength?): value is BrandedHash;
Type guard that checks whether a value is a valid hash of the specified bit length.
unknown
The value to check
HashBitLength = 256
The expected bit length of the hash (defaults to 256)
value is BrandedHash
True if the value is a valid Hash
### <a id="isHashBitLength"></a>isHashBitLength
function isHashBitLength(value): value is HashBitLength;
Type guard that checks whether a value is a valid hash bit length.
unknown
The value to check
value is HashBitLength
True if the value is one of the supported HashBitLength values
### <a id="isHex"></a>isHex
function isHex(value, config?): value is BrandedHex;
Type guard that checks whether a value is a valid hex string.
unknown
The value to check
Optional configuration for prefix and bit length validation
value is BrandedHex
True if the value is a valid Hex string
### <a id="isHexZero"></a>isHexZero
function isHexZero(value?): boolean | undefined;
Checks whether a hex string represents a zero value.
string
The hex string to check
boolean | undefined
True if zero, false if non-zero, or undefined if the input is not a string
### <a id="nibblesToBits"></a>nibblesToBits
function nibblesToBits(value): number;
Converts a nibble count to the equivalent number of bits.
number
The number of nibbles
number
The number of bits
### <a id="toAddress"></a>toAddress
function toAddress(value, config?): BrandedAddress;
Converts a value to a 160-bit Address hex string.
string | number | bigint | ArrayBufferLike
The value to convert (string, number, bigint, or ArrayBuffer)
HexConfig = {}
Optional hex config (defaults to 160-bit, no prefix)
BrandedAddress
The value as an Address
### <a id="toAddressV2"></a>toAddressV2
function toAddressV2(value, assert?): BrandedAddress | undefined;
Alpha
unknown
boolean = false
BrandedAddress | undefined
### <a id="toEthAddress"></a>toEthAddress
function toEthAddress(value, config?): EthAddress;
Converts a value to a 0x-prefixed Ethereum address string.
string | number | bigint | ArrayBufferLike
The value to convert (string, number, bigint, or ArrayBuffer)
HexConfig = {}
Optional hex config (defaults to 160-bit, no inner prefix)
The value as an EthAddress
### <a id="toHex"></a>toHex
function toHex(value, config?): BrandedHex;
takes any value and tries our best to convert it to a hex string
string | number | bigint | ArrayBufferLike
Supported types are string, number, bigint, and ArrayBuffer
HexConfig = {}
Configuration of output format and validation
### <a id="toHexLegacy"></a>toHexLegacy
function toHexLegacy(buffer): string;
Converts an ArrayBuffer to a hex string without padding or normalization.
ArrayBuffer
The ArrayBuffer to convert
string
A lowercase hex string representation of the buffer
### interfaces
### <a id="HexConfig"></a>HexConfig
Configuration of validation and output format
optional bitLength?: number;
optional byteSize?: number;
optional prefix?: boolean;
### type-aliases
### <a id="Address"></a>Address
type Address = z.infer<typeof AddressZod>;
A validated 20-byte address string type, inferred from the AddressZod schema.
### <a id="AddressTransformZodType"></a>AddressTransformZodType
type AddressTransformZodType = z.infer<typeof AddressTransformZod>;
The output type of AddressTransformZod after parsing and transformation.
### <a id="AddressValidationZodType"></a>AddressValidationZodType
type AddressValidationZodType = z.infer<typeof AddressValidationZod>;
The output type of AddressValidationZod after parsing.
### <a id="BrandedHash"></a>BrandedHash
type BrandedHash = Brand<Hex, {
__hash: true;
}>;
Branded type representing a validated hash hex string.
### <a id="BrandedHex"></a>BrandedHex
type BrandedHex = Brand<Lowercase<string>, {
__hex: true;
}>;
Branded type representing a validated lowercase hex string.
### <a id="EthAddress"></a>EthAddress
type EthAddress = Brand<string, {
__eth_address: true;
}>;
Branded type representing a validated Ethereum address with 0x prefix.
### <a id="Hash"></a>Hash
type Hash = z.infer<typeof HashZod>;
A validated hash string type, inferred from the HashZod schema.
### <a id="HashBitLength"></a>HashBitLength
type HashBitLength = 32 | 64 | 128 | 256 | 512 | 1024 | 2048 | 4096;
Valid bit lengths for hash values.
### <a id="Hex"></a>Hex
type Hex = z.infer<typeof HexZod>;
A validated hex string type, inferred from the HexZod schema.
### variables
### <a id="ADDRESS_LENGTH"></a>ADDRESS_LENGTH
const ADDRESS_LENGTH: 40;
The character length of an address hex string (40 hex characters / 20 bytes).
### <a id="AddressRegEx"></a>AddressRegEx
const AddressRegEx: RegExp;
Regular expression matching a 20-byte (40 hex character) address string.
### <a id="AddressTransformZod"></a>AddressTransformZod
const AddressTransformZod: ZodPipe<ZodPipe<ZodUnion<readonly [ZodString, ZodBigInt, ZodNumber]>, ZodTransform<string, string | number | bigint>>, ZodTransform<BrandedAddress, string>>;
Zod schema that accepts a string, bigint, or number and transforms it into a validated Address.
### <a id="AddressValidationZod"></a>AddressValidationZod
const AddressValidationZod: ZodPipe<ZodString, ZodTransform<BrandedAddress, string>>;
Zod schema that validates a string is a properly formatted 40-character hex address.
### <a id="AddressZod"></a>AddressZod
const AddressZod: ZodPipe<ZodString, ZodTransform<BrandedAddress, string>>;
Zod schema that validates and transforms a string into a branded Address type.
### <a id="BigIntToJsonZod"></a>BigIntToJsonZod
const BigIntToJsonZod: ZodPipe<ZodBigInt, ZodTransform<BrandedHex, bigint>>;
Zod schema that transforms a non-negative BigInt into a hex string for JSON serialization.
### <a id="ETH_ZERO_ADDRESS"></a>ETH_ZERO_ADDRESS
const ETH_ZERO_ADDRESS: EthAddress;
The zero Ethereum address constant (0x followed by 40 zero characters).
### <a id="EthAddressFromStringSchema"></a>EthAddressFromStringSchema
const EthAddressFromStringSchema: ZodPipe<ZodString, ZodTransform<EthAddress, string>> = EthAddressFromStringZod;
use EthAddressFromStringZod
### <a id="EthAddressFromStringZod"></a>EthAddressFromStringZod
const EthAddressFromStringZod: ZodPipe<ZodString, ZodTransform<EthAddress, string>>;
Zod schema that validates and transforms a string into an EthAddress type.
### <a id="EthAddressRegEx"></a>EthAddressRegEx
const EthAddressRegEx: RegExp;
Regular expression matching a 20-byte Ethereum address with 0x prefix (mixed case).
### <a id="EthAddressToStringSchema"></a>EthAddressToStringSchema
const EthAddressToStringSchema: ZodString = EthAddressToStringZod;
use EthAddressToStringZod
### <a id="EthAddressToStringZod"></a>EthAddressToStringZod
const EthAddressToStringZod: ZodString;
Zod schema that validates a string is a properly formatted Ethereum address.
### <a id="EthAddressZod"></a>EthAddressZod
const EthAddressZod: ZodString & ZodType<EthAddress, string, $ZodTypeInternals<EthAddress, string>>;
Zod schema that validates a string as a properly formatted Ethereum address using regex and type guard.
### <a id="HASH_LENGTH"></a>HASH_LENGTH
const HASH_LENGTH: 32;
The byte length of a standard hash (32 bytes / 256 bits).
### <a id="HashBitLength"></a>HashBitLength
HashBitLength: HashBitLength[];
Array of all valid hash bit lengths for runtime validation.
### <a id="HashRegEx"></a>HashRegEx
const HashRegEx: RegExp;
Regular expression matching a 32-byte (64 hex character) hash string.
### <a id="HashToJsonZod"></a>HashToJsonZod
const HashToJsonZod: ZodPipe<ZodPipe<ZodString, ZodTransform<BrandedHash, string>>, ZodTransform<string, BrandedHash>>;
Zod schema that transforms a Hash to a plain string for JSON serialization.
### <a id="HashZod"></a>HashZod
const HashZod: ZodPipe<ZodString, ZodTransform<BrandedHash, string>>;
Zod schema that validates and transforms a string into a branded Hash type.
### <a id="HexRegEx"></a>HexRegEx
const HexRegEx: RegExp;
Regular expression matching a lowercase hex string without prefix.
### <a id="HexRegExWithPrefix"></a>HexRegExWithPrefix
const HexRegExWithPrefix: RegExp;
Regular expression matching a lowercase hex string with a 0x prefix.
### <a id="HexZod"></a>HexZod
const HexZod: ZodPipe<ZodString, ZodTransform<BrandedHex, string>>;
Zod schema that validates and transforms a string into a branded Hex type.
### <a id="JsonToBigIntZod"></a>JsonToBigIntZod
const JsonToBigIntZod: ZodPipe<ZodPipe<ZodString, ZodTransform<BrandedHex, string>>, ZodTransform<bigint, BrandedHex>>;
Zod schema that parses a JSON hex string into a BigInt.
### <a id="JsonToHashZod"></a>JsonToHashZod
const JsonToHashZod: ZodPipe<ZodString, ZodTransform<BrandedHash, string>>;
Zod schema that parses a JSON string into a validated Hash, throwing on invalid input.
### <a id="ZERO_ADDRESS"></a>ZERO_ADDRESS
const ZERO_ADDRESS: BrandedAddress;
A 160-bit zero address constant.
### <a id="ZERO_HASH"></a>ZERO_HASH
const ZERO_HASH: BrandedHash;
A 256-bit zero hash constant.
FAQs
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
The npm package @xylabs/hex receives a total of 3,702 weekly downloads. As such, @xylabs/hex popularity was classified as popular.
We found that @xylabs/hex demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Bitwarden CLI 2026.4.0 was compromised in the Checkmarx supply chain campaign after attackers abused a GitHub Action in Bitwarden’s CI/CD pipeline.
Research
/Security News
Docker and Socket have uncovered malicious Checkmarx KICS images and suspicious code extension releases in a broader supply chain compromise.
Product
Stay on top of alert changes with filtered subscriptions, batched summaries, and notification routing built for triage.