Effect Schema codecs for hexadecimal strings and bytes. Each schema decodes a hex string into one normalised form and encodes it back to its wire format: lowercase, 0x-prefixed, colon-separated (the fingerprint form, such as AB:CD:0F), or a Uint8Array.
import { ColonHex, PrefixedHex, Uint8ArrayFromPrefixedHex } from '@systemfsoftware/hex-schema'
import { Schema as S } from 'effect'
S.decodeUnknownSync(PrefixedHex)('0xabcd') // 'abcd'
S.decodeUnknownSync(ColonHex)('ab:cd:0f') // 'abcd0f'
S.decodeUnknownSync(Uint8ArrayFromPrefixedHex)('0x0aff') // Uint8Array(2) [ 10, 255 ]PrefixedHex rejects uppercase digits, so S.decodeUnknownSync(PrefixedHex)('0xABcd') throws.
pnpm add @systemfsoftware/hex-schema effecteffect@^4 is a peer dependency: you bring your own.
The repository publishes two packages. @systemfsoftware/hex-schema holds the schemas. @systemfsoftware/effect-schema-extensions re-exports everything in @systemfsoftware/hex-schema, from its root and from its ./hex-schema subpath, so either one gives you the same names.
| Schema | Accepts | Decodes to | Encodes to |
|---|---|---|---|
StrictHex |
lowercase hex, no prefix; empty allowed | the same string | the same string |
HexString |
optional 0x; any case; any length |
lowercase, no prefix | the same string |
PrefixedHex |
0x, then lowercase hex; 0x alone is empty |
lowercase, no prefix | 0x-prefixed |
ColonHex |
1 or 2 hex digits per byte, colon-separated, any case; empty allowed | lowercase, no colons | uppercase, colon-separated |
HexBytes |
hex string of even length, either case | Uint8Array |
lowercase hex |
Uint8ArrayFromPrefixedHex |
0x, then lowercase hex of even length |
Uint8Array |
0x-prefixed hex |
HexString, PrefixedHex and ColonHex decode to branded strings, so a plain string does not type-check where one of them is required.
Two differences matter when you mix schemas:
HexStringaccepts an odd number of digits, such asabc. The byte schemas,HexBytesandUint8ArrayFromPrefixedHex, reject it.HexStringandHexBytesaccept uppercase digits.PrefixedHexandUint8ArrayFromPrefixedHexreject them.
Development setup and workflow are in CONTRIBUTING.md.
Report bugs and ask questions in the issue tracker.