utils

Shared TypeScript utilities for removing repeated code across Sovereignbase codebases.

Compatibility

• Runtimes: modern JavaScript runtimes; the repository includes runtime compatibility tests for Node, Bun, Deno, Cloudflare Workers, Edge Runtime, and browsers.
• Module format: ESM and CommonJS.
• Required globals / APIs: structuredClone is required for successful safeStructuredClone() results.
• Browser capability checks: browserHasSovereignbaseDependencies() resolves to false outside secure browser contexts and when required browser APIs are missing.
• TypeScript: bundled types.

Goals

• Remove repeated utility code from Sovereignbase repositories.
• Keep shared helpers small, explicit, and side-effect free.
• Validate behavior across the runtimes used in Sovereignbase projects.

Installation

npm install @sovereignbase/utils
# or
pnpm add @sovereignbase/utils
# or
yarn add @sovereignbase/utils
# or
bun add @sovereignbase/utils
# or
deno add jsr:@sovereignbase/utils
# or
vlt install jsr:@sovereignbase/utils

Usage

prototype()

import { prototype } from '@sovereignbase/utils'

prototype(null) // 'null'
prototype({ ok: true }) // 'record'
prototype(new URL('https://sovereignbase.dev')) // 'url'

Returns a normalized lowercase runtime tag for common primitives, serializable built-ins, and selected platform objects.

isUuidV7()

import { isUuidV7 } from '@sovereignbase/utils'

const value = '018f0d1e-6c82-7d4b-91c1-8a7b5e2f4a10'

if (isUuidV7(value)) {
  value // string, confirmed UUID v7
}

Checks that a value is a syntactically valid UUID version 7 string.

isUuidV7BigInt()

import { isUuidV7BigInt } from '@sovereignbase/utils'

const value = 0x018f0d1e6c827d4b91c18a7b5e2f4a10n

if (isUuidV7BigInt(value)) {
  value // bigint, confirmed UUID v7 bit layout
}

Checks that a bigint is inside the 128-bit UUID range and has UUID version 7 and RFC 4122 variant bits.

isRecord()

import { isRecord } from '@sovereignbase/utils'

const value: unknown = { ok: true }

if (isRecord(value)) {
  value.ok // unknown
}

Checks that a value is a plain object record: non-null, not an array, and backed by an Object constructor prototype.

safeBigIntFromString()

import { safeBigIntFromString } from '@sovereignbase/utils'

const result = safeBigIntFromString('9007199254740993')

if (result !== false) {
  result // 9007199254740993n
}

Converts a string to a bigint using JavaScript BigInt() string conversion semantics and returns false instead of throwing for invalid input.

uuidV7BigIntStringToBigInt()

import { uuidV7BigIntStringToBigInt } from '@sovereignbase/utils'

const value = uuidV7BigIntStringToBigInt(
  '2071992528307252230503468673270762000'
)

if (value !== false) {
  value // bigint, confirmed UUID v7 bit layout
}

Converts a bigint string to a bigint and returns it only when the resulting value has a UUID v7 bit layout.

safeStructuredClone()

import { safeStructuredClone } from '@sovereignbase/utils'

const result = safeStructuredClone({ ok: true, nested: { count: 1 } })

if (result[0]) {
  const clone = result[1]
  clone // deep cloned value
}

Attempts a structured clone and returns a tuple instead of throwing on unsupported values.

getISO31661Alpha2CountryCodeSet()

import {
  type ISO31661Alpha2,
  getISO31661Alpha2CountryCodeSet,
} from '@sovereignbase/country-codes'

function epicFunction1(countryCode: ISO31661Alpha2) {
  const countryCodes = getISO31661Alpha2CountryCodeSet()
  const isCountryCode = countryCodes.has(countryCode)
  if (!isCountryCode) throw new Error('THAT IS NOT A COUNTRY CODE DUDE!')
  console.log('EPIC COUNTRY CODE MOMENT:', countryCode)
}

Returns a fresh Set containing all supported ISO 3166-1 alpha-2 country codes.

browserHasSovereignbaseDependencies()

import { browserHasSovereignbaseDependencies } from '@sovereignbase/utils'

if (await browserHasSovereignbaseDependencies()) {
  console.log('browser runtime supports Sovereignbase dependencies')
}

Checks whether the current browser environment exposes the secure-context, storage, worker, notification, Web Crypto, and WebAuthn APIs required by Sovereignbase browser features.

afterIdleFor()

import { afterIdleFor } from '@sovereignbase/utils'

const saveAfterTypingStops = afterIdleFor(500, () => {
  console.log('save draft')
})

document.addEventListener('input', saveAfterTypingStops)

Creates a function that resets a timer on every call and runs the callback after the requested idle timeout.

Tests

• Latest local npm run test run passed on Node v22.14.0.
• Node unit suite: 15/15 passed.
• Node integration suite: 2/2 passed.
• Coverage: 100% statements, branches, functions, and lines.
• Runtime E2E: Node ESM 17/17 passed.
• Runtime E2E: Node CJS 17/17 passed.
• Runtime E2E: Bun ESM 17/17 passed.
• Runtime E2E: Bun CJS 17/17 passed.
• Runtime E2E: Deno ESM 17/17 passed.
• Runtime E2E: Cloudflare Workers ESM 17/17 passed.
• Runtime E2E: Edge Runtime ESM 17/17 passed.
• Browser E2E: 5/5 Playwright projects passed (chromium, firefox, webkit, mobile-chrome, mobile-safari).

Benchmarks

• Latest local npm run bench run: Node v22.14.0 on win32 x64. | Function / scenario | ops/sec | ms/op | | ----------------------------------- | ----------: | ----------: | | prototype(record) | 11,402,112 | 0.000087703 | | prototype(url) | 6,015,126 | 0.000166248 | | isRecord(record) | 21,025,895 | 0.000047560 | | isRecord(array) | 128,470,304 | 0.000007784 | | isUuidV7(valid) | 6,141,601 | 0.000162824 | | isUuidV7(invalid) | 6,548,055 | 0.000152717 | | isUuidV7BigInt(valid) | 14,002,141 | 0.000071418 | | isUuidV7BigInt(invalid) | 23,886,415 | 0.000041865 | | safeBigIntFromString(valid) | 10,990,605 | 0.000090987 | | safeBigIntFromString(invalid) | 106,885 | 0.009355836 | | uuidV7BigIntStringToBigInt(valid) | 3,574,185 | 0.000279784 | | uuidV7BigIntStringToBigInt(invalid) | 3,893,438 | 0.000256842 | | getISO31661Alpha2CountryCodeSet() | 99,879 | 0.010012102 | | safeStructuredClone(record) | 226,399 | 0.004416974 | | safeStructuredClone(function) | 54,352 | 0.018398538 | | afterIdleFor(callback) | 2,982,528 | 0.000335286 |

• Results vary by machine.

License

Apache-2.0