A lean, zero dependency library to provide a useful base for your project. Checksums, cryptography, codecs, date-times, error-checking-codes, logging, pseudorandom number generation. The tools you need for any project. Secure build pipeline, provenance signed and typed.
- Installation
- License
- Features:
- Augmented Backus-Naur Form
- Checksum/Hashsum
- Command Line Interface (arguments, colour, text style)
- Codecs
- Symmetric Encryption
- Secure Hashing
- Key derivation functions
- Message Authentication Codes
- EXtendable-Output Functions
- DateTime
- Error Correction Code
- Endian
- Primitive Types
- Seedable PseudoRandom number generators
- RegExp tools
- Run time tools (environment vars, logging, stack traces)
Ƃ = Bytes
b = bits
This module is available through NPM. There are no install scripts, decrease your risk by explicitly preventing (--ignore-scripts)
(pnpm|npm) install gnablib --ignore-scriptsTo verify provenance:
npm audit signaturesAugmented Backus-Naur Form /rfc5234
- Operators
- Definition of core rules
- Weighted Random Sampling
- Thomson NFA (1968) solver
A checksum; can be used to prevent/identify accidental changes.
| Name | Sum size Ƃ |
|---|---|
| Adler32 | 4 |
| Block Check Character | 1 |
| Cksum | 4 |
| CRC24 | 3 |
| CRC32 | 4 |
| Fletcher16 | 2 |
| Fletcher32 | 4 |
| Fletcher64 | 8 |
| Longitudinal Redundancy Check | 1 |
The Luhn algorithm is also support, which only works on integers/numerical digits (eg. credit cards, SI numbers)
A hash; maps some data to another, often used for hash tables, or to speed up comparison. We use the term hashsum to distinguish from cryptographic-hashes (although MD5 and SHA1 were once cryptographically safe)
| Name | Sum size Ƃ | Optional parameters |
|---|---|---|
| Lookup2 | 4 | seed |
| Lookup3 | 4+4/8 | seed |
| MD5Sum | 16 | |
| Murmur3 | 4 | seed |
| SHA1Sum | 20 | |
| Spooky v2 | 16 | seed |
| xxHash32 | 4 | seed |
| xxHash64 | 8 | seed |
- Argument and option parsing
- Foreground, background color (8 color, 213 color, 16M colors)
- Underline, bold, faint, italic, blink, invert, hide, strike-through, overline text styles
- Terminal controls & style (cursor move, screen/line clear)
- ASCII85
- Base32, zBase32, Base32Hex, Crockford32
- Base64, Base64url, B64
- bfloat16
- Densely Packed Decimal
- Hex
- IEEE754 Binary
- Proquint
- QuotedPrintable
- ROT13, ROT13.5, ROT47
- Scream
- URI
- UTF8
- uuencode
- UUID
- YEnc
- Cipher Block Chaining (CBC)
- Cipher FeedBack (CFB)
- Counter (CTR)
- Electronic CodeBook (ECB)
- Output FeedBack (OFB)
CBC or CTR are recommended by Niels Ferguson and Bruce Schneier. ECB should not be used.
- ANSI X9.23 / ISO 10126 padding
- ISO 7816-4 padding
- ISO 9797-1 padding 2
- PKCS#7 / PKCS#5 padding
- Zero / Null padding
| Name | Block Ƃ | Key Ƃ | Nonce Ƃ | Features |
|---|---|---|---|---|
| Advanced Encryption Standard (AES) | 16 | 16, 24, 32 | 0 | |
| ARIA | 16 | 16, 24, 32 | 0 | |
| Ascon-128 | 8, 16 | 16 | 16 | AEAD |
| Ascon-80pq | 8 | 20 | 16 | +Quantum resistance |
| Blowfish | 8 | 4-56 | 0 | |
| ChaCha20 | 64 | 16, 32 | 12 | |
| ChaCha20-Poly1305 | 64 | 32 | 12 | AEAD |
| Lightweight Encryption Algorithm (LEA) | 16 | 16, 24, 32 | 0 | |
| Rabbit | 16 | 16 | 0, 8 | |
| Salsa20 | 64 | 16, 32 | 8 | |
| Salsa20-Poly1305 | 64 | 32 | 12 | AEAD |
| Serpent | 16 | 16, 24, 32 | 0 | |
| Simon64 | 8 | 12, 16 | 0 | |
| Simon128 | 16 | 16, 24, 32 | 0 | |
| SM4 | 16 | 16 | 0 | |
| Speck64 | 8 | 12, 16 | 0 | |
| Speck128 | 16 | 16, 24, 32 | 0 | |
| Threefish256 | 16 | 16 | ~16 | Tweak (nonce/AEAD) |
| Threefish512 | 32 | 32 | ~16 | Tweak (nonce/AEAD) |
| Threefish1024 | 64 | 64 | ~16 | Tweak (nonce/AEAD) |
| Twofish | 16 | 16, 24, 32 | 0 | |
| XChaCha20 | 64 | 32 | 24 | |
| XChaCha20-Poly1305 | 64 | 32 | 24 | AEAD |
| XSalsa20 | 64 | 16, 32 | 24 | |
| XSalsa20-Poly1305 | 64 | 32 | 24 | AEAD |
Cryptography hash functions that have the properties:
- Finding an input string that matches a hash value (pre-image) is hard
- Finding a pair of messages that generate the same hash value (collision) is hard
| Name | Digest Ƃ | Optional parameters |
|---|---|---|
| Ascon-Hash, Ascon-HashA | 32 | - |
| Blake | 32, 64 | salt |
| Blake2b | 1-64, 32, 48, 64 | key, salt, personalization |
| Blake2s | 1-32, 28, 32 | key, salt, personalization |
| Keccak | 1-64, 28, 32, 48, 64 | capacity |
| MD4† | 16† | - |
| MD5† | 16† | - |
| ParallelHash (128,256) | 1-64 | block size, customization |
| RipeMD† | 16†, 20†, 32, 40 | - |
| SHA-1† | 20† | - |
| SHA-2 | 28, 32, 48, 64, 64/28, 64/32 | - |
| SHA-3 | 28, 32, 48, 64 | - |
| TupleHash (128, 256) | 1-64 | customization |
| Whirlpool | 64 | - |
† No longer considered cryptographically safe
A cryptographic algorithm that derives one or more secret keys from a secret value. Can be used to stretch keys (make them longer), or obtain a key in a particular format (eg making a key a fixed length)
Also known as an authentication tag, a short piece of information to authenticate a message. Protect integrity, and authenticity.
| Name | Tag Ƃ |
|---|---|
| CMAC | 16 (AES) |
| HMAC | Depends on hash (Blake, Blake2, cShake, Keccak, MD4, MD5, RipeMD, Sha1, Sha2, Sha3, Shake, Whirlpool) |
| HopMAC | 16 (Kangaroo Twelve) |
| KMAC | 16, 32 (Keccak) |
| Poly1305 | 16 |
A secure hash that can produce output of any desired length.
| Name | Capacity Ƃ | Optional parameters |
|---|---|---|
| Ascon-Xof, Ascon-XofA | 32 | digest size |
| cShake | 16, 32 | digest size, function name, customization |
| KangarooTwelve | 16 | digest size, customization |
| KmacXof | 16, 32 | digest size, key, customization |
| ParallelHashXof | 16, 32 | block size, digest size, customization |
| Shake | 16, 32 | digest size |
| TupleHashXof | 16, 32 | digest size, customization |
| TurboSHAKE | 16, 32 | digest size, customization |
- Year, Month, Day
- Hour, Minute, Second, Millisecond, Microsecond
- DateTimeLocal, DateTimeUtc, DateOnly, TimeOnly
- Duration, DurationExact
- DateTime*.lt|lte|eq|gt|gte|neq - Compare two date-times
- DateTime*.add|sub - Add or subtract Duration|DurationExact from a date-time
- DateTime*.diff|diffExact - Get the difference between two dates in y/m/d/h/* or d/h/*
- Convert between big (BE) and little (LE) Endian encoding 16/32/64/128 bits, or a stream of bytes.
- Detects platform endianness
Big endian is closer to the way we write numbers left-to-right in English. 1726 = 1x1000, 7x100, 2x10, 6x1
Little endian is the dominant ordering for processor architectures including; x86 and RISC-V, ARM can be either but defaults to little. Famous big endian processors include PDP-10, Motorola 68000 series (early Macintosh, Amiga, Atari, Sega), IBM Z and SPARC, which can be either but default to big.
- BitReader / BitWriter
- Fixed TypedArray
- Lazy
- Network CIDR, IPv4
- Readonly TypedArray
- Scaling TypedArray
- StringBuilder
- WindowStr
- 16 bit: uint (U16) 2Ƃ
- 32 bit: uint (U32), mutable uint (U32Mut), mutable uint array (U32MutArray) 4Ƃ
- 64 bit: int (I64), uint (U64), mutable int (I64Mut), mutable uint (U64Mut), mutable uint array (U64MutArray) 8Ƃ
- 128 bit: uint (U128), mutable uint (U128Mut) 16Ƃ
- 256 bit: uint (U256) 32Ƃ
- 512 bit: uint (U512) 64Ƃ
- Bit (countBitsSet, lsbMask, reverse, countLeadZeros, nextPow2)
- Float (parseDec)
- Int (parseDec, parseHex, parseCsv)
- String (splitChars, splitLen, reverse, padStart, filter, ctEq, ctSelect)
- Uint (parseDec, parseHex, sign8, sign16, sign32, glScaleSize, toGlScaleBytes, fromGlScaleBytes)
- Uint8Array (toGlBytes, ctEq, ctSelect, incrBE, lShiftEq, xorEq)
Use one of these if you can, alphabetically sorted. gjrand32b is only somewhat official and doesn't have a lot of testing.
| Name | Year | Variant | State Ƃ | Out b | Safe b | |
|---|---|---|---|---|---|---|
| GJRand | 2005 | ~gjrand32b | 16 | 32 | 〃 | |
| gjrand64 | 32 | ‡ | 64 | 〃 | ||
| Permuted Congruential Generator (PCG) | 2014 | pcg32 | 8 | ‡ | 32 | 〃 |
| pcg64 | 16 | ‡ | 64 | 〃 | ||
| Small Fast Counting (SFC) | 2010 | sfc16 | 8 | 16 | 〃 | |
| sfc32 | 16 | 32 | 〃 | |||
| sfc64 | 32 | ‡ | 64 | 〃 | ||
| SplitMix | 2014 | splitmix32 | 4 | 32 | 〃 | |
| splitmix64 | 8 | ‡ | 64 | 〃 | ||
| Tychei | 2011 | tychei | 16 | 32 | 〃 | |
| Well equidistributed long-period linear (WELL) | 2006 | well512 | 64 | 32 | 〃 | |
| XoRoShiRo | 2018 | xoroshiro64* | 8 | 32 | 〃 | |
| xoroshiro64** | 8 | 32 | 〃 | |||
| xoroshiro128+ | 16 | ‡ | 64 | 53 | ||
| xoroshiro128++ | 16 | ‡ | 64 | 〃 | ||
| xoroshiro128** | 16 | ‡ | 64 | 〃 | ||
| XorShift+ | 2003 | xorshift128+ | 16 | ‡ | 64 | 〃 |
| XoShiRo | 2018 | xoshiro128+ | 16 | 32 | 24 | |
| xoshiro128++ | 16 | 32 | 〃 | |||
| xoshiro128** | 16 | 32 | 〃 | |||
| xoshiro256+ | 32 | ‡ | 64 | 53 | ||
| xoshiro256++ | 32 | ‡ | 64 | 〃 | ||
| xoshiro256** | 32 | ‡ | 64 | 〃 |
‡: Use U64 library to exceed JS 32bit integer constraint (may be slower)
U16
: [0 - 32767 | 0xFFFF]
U31
: [0 - 2147483647 | 0x7FFFFFFF]
U32
: [0 - 4294967295 | 0xFFFFFFFF]
U64
: [0 - 18446744073709551615 | 0xFFFFFFFFFFFFFFFF]
Best not to use these, there are some dragons in these waters (so if you're choosing, be aware of the limitations). However, you might have a compatibility constraint (or love the name "Mersenne Twister").
| Name | Year | Variant | State Ƃ | Out b |
|---|---|---|---|---|
| ARC4/RC4/Arcfour/Arc4random | 1997 | arc4 | 258 | 8 |
| Mersenne Twister | 1998 | mt19937 | 2496 | 32 |
| MulBerry32 | 2017 | mulberry32 | 4 | 32 |
| XorShift | 2003 | xorshift128 | 16 | 32 |
If you're curious about the lineage, or need for compatibility with an old decision, but don't chose one of these. If you're already using one of these, consider migrating.
| Name | Variant | State Ƃ | Out b |
|---|---|---|---|
| Lehmer/LCG/MCG 1988 | all | 4 | 31 |
| Marsaglia | - | 1 | 4 |
| Middle-Square | - | 4 | n digits |
| MSVC (LCG) | - | 4 | 16 |
| RANDU (LCG) | - | 4 | 31 |
| XorShift 2003 | xorshift32 | 4 | 32 |
| xorshift64 | 8 | 64 |
- RegExp escape string
- Configuration (including collecting from environment variables)
- Structured logging
- Normalize stack entries, and stack traces across engines, with colors
Copyright © 2022-2025 gnablib contributors