Crypto Utilities

The Crypto utilities provide functions for generating unique identifiers and hash codes in JavaScript. These functions are useful for creating unique keys, generating consistent hashes for objects, and other cryptographic purposes.

Functions

hashCode

function hashCode(input, { usage = 'hash', format, seed = 0 } = {})

Deterministic content hash: the same input always produces the same output. Pick a usage by what the hash is for, not by algorithm (it runs cyrb53 for the sync rungs and SHA-256 for secure). The return type follows the usage. For unique ids that are not derived from content, use generateId instead.

Usage presets

Parameters

Options

Defaults can be set globally on the mutable hashCode.config object (precedence: call options > config > preset). ignoreConfig opts a call out of that global layer — for library code that needs the same output shape regardless of host-app defaults.

Returns

A 53-bit number (hash), an encoded string (content / fingerprint), or a Promise<string> (secure). format overrides the encoding.

Example

import { hashCode } from '@semantic-ui/utils';

console.log(hashCode("Hello, world!"));                             // 53-bit number
console.log(hashCode("Hello, world!", { usage: 'content' }));      // 64-bit crockford string
console.log(hashCode("Hello, world!", { usage: 'fingerprint' }));  // 128-bit crockford string
console.log(await hashCode("Hello, world!", { usage: 'secure' })); // SHA-256 string
console.log(hashCode("Hello, world!", { usage: 'content', format: 'hex' }));
console.log(hashCode({ a: 1, b: [2, 3] }));

// global default for a whole app
hashCode.config = { usage: 'content' };

generateId

function generateId({ usage = 'db', length, bits, prefix, checksum, upper, format = 'crockford', group } = {})

Generates a unique id. Defaults to a sortable 26-char ULID (usage db). Each usage preset names what the id is for and carries the length, alphabet, and structure that fits that channel. The inverse is isValidId and parseId.

Usage presets

A preset states its width in the unit its channel is chosen by. link is 11 characters because a link has to fit somewhere. secret is 256 bits because that is the number a security review asks for, and it clears the field: the Copenhagen Book floors server-side tokens at 112 bits, a 32-byte secret is the common recommendation, and shipped implementations sit near 190. Rounding up to a whole Crockford character emits 260 bits over 52 random characters, with the 53rd holding the check character. Both tiers are unguessable. Reach for token where the id also travels in a URL and gets read back by a person, secret where it is a credential.

Options

Defaults can be set globally on the mutable generateId.config object (precedence: call options > config > preset). ignoreConfig opts a call out of that global layer — for library code whose id shapes must not bend to host-app defaults. isValidId and parseId take it too, so an id minted config-free validates config-free. Width follows the same precedence, so an app-wide length narrows secret like any other preset. Code that mints a credential and must hold its own width passes ignoreConfig: true.

Returns

The generated id string.

Example

import { generateId } from '@semantic-ui/utils';

console.log(generateId());                                  // '01KV61ZF26Z6BG7T04NVKSPJ7K'
console.log(generateId({ usage: 'page' }));                 // 'dzadahv3'
console.log(generateId({ usage: 'link' }));                 // '9zv38gp9ybm'
console.log(generateId({ usage: 'token', prefix: 'sk_' })); // 'sk_…' with a checksum
console.log(generateId({ usage: 'secret' }));               // 53-char, 256-bit session secret
console.log(generateId({ usage: 'code' }));                 // 'ABCD-EFGH-JKLM' grouped, checksummed
console.log(generateId({ length: 17 }));                    // 17-char id
console.log(generateId({ usage: 'secret', bits: 512 }));    // wider, same shape
console.log(generateId({ format: 'uuid' }));                // RFC UUIDv7

// global default for a whole app
generateId.config = { usage: 'page' };

// library code opts out of the global layer
console.log(generateId({ ignoreConfig: true }));            // 26-char ULID, config ignored

isValidId

function isValidId(id, options)

Validates an id offline against the same options that would generate it — the cheap rejection before an expensive lookup. Reads loose: folds case, maps I/L to 1 and O to 0, and ignores hyphens, then checks the prefix, length, alphabet, and checksum.

Parameters

Returns

true if the id is well-formed for that config, otherwise false.

Example

import { generateId, isValidId } from '@semantic-ui/utils';

const id = generateId({ usage: 'token', prefix: 'sk_' });
console.log(isValidId(id, { usage: 'token', prefix: 'sk_' })); // true
console.log(isValidId('sk_typoatthestart', { usage: 'token', prefix: 'sk_' })); // false

parseId

function parseId(id, options)

Splits a valid id into { prefix, body, checksum }, decoding timestamp for the db preset. Returns null for anything isValidId rejects. There is no in-band signal, so parsing always needs the config that minted the id.

Parameters

Returns

{ prefix, body, checksum, timestamp? }, or null if invalid. timestamp (a Date) is present only for the db preset.

Example

import { generateId, parseId } from '@semantic-ui/utils';

const id = generateId({ usage: 'db', prefix: 'doc_' });
const parsed = parseId(id, { usage: 'db', prefix: 'doc_' });
console.log(parsed.prefix);    // 'doc_'
console.log(parsed.timestamp); // Date — when the id was minted

getRandomSeed

function getRandomSeed()

Generates a cryptographically secure random seed value.

Returns

A random 32-bit unsigned integer, from crypto.getRandomValues.

Example

import { getRandomSeed } from '@semantic-ui/utils';

console.log(getRandomSeed()); // 2949673445
console.log(getRandomSeed()); // 1234567890