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.

isUint32()

import {
  isUint32,
  UINT32_MIN,
  UINT32_MAX,
  UINT32_SIZE,
} from '@sovereignbase/utils'

const value: unknown = 4_294_967_295

if (isUint32(value)) {
  value // number, confirmed unsigned 32-bit integer
}

Checks that a value is a JavaScript number representing an integer in the inclusive unsigned 32-bit range, 0 through 2^32 - 1.

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 exec --yes --package deno -- npm run test run passed on Node v24.16.0.
• Node unit suite: 16/16 passed.
• Node integration suite: 2/2 passed.
• Coverage: 100% statements, branches, functions, and lines.
• Runtime E2E: Node ESM 18/18 passed.
• Runtime E2E: Node CJS 18/18 passed.
• Runtime E2E: Bun ESM 18/18 passed.
• Runtime E2E: Bun CJS 18/18 passed.
• Runtime E2E: Deno ESM 18/18 passed.
• Runtime E2E: Cloudflare Workers ESM 18/18 passed.
• Runtime E2E: Edge Runtime ESM 18/18 passed.
• Browser E2E: 5/5 Playwright projects passed (chromium, firefox, webkit, mobile-chrome, mobile-safari).

Benchmarks

• Latest local npm run bench run: Node v24.16.0 on win32 x64.

  Function / scenario	ops/sec	ms/op
  prototype(record)	10,048,999	0.000099512
  prototype(url)	4,919,298	0.000203281
  isRecord(record)	22,128,887	0.000045190
  isRecord(array)	135,978,570	0.000007354
  isUint32(valid)	143,928,381	0.000006948
  isUint32(invalid)	148,897,045	0.000006716
  isUuidV7(valid)	4,852,110	0.000206096
  isUuidV7(invalid)	5,036,241	0.000198561
  isUuidV7BigInt(valid)	17,177,054	0.000058217
  isUuidV7BigInt(invalid)	26,694,821	0.000037460
  safeBigIntFromString(valid)	10,009,579	0.000099904
  safeBigIntFromString(invalid)	101,179	0.009883494
  uuidV7BigIntStringToBigInt(valid)	5,583,083	0.000179113
  uuidV7BigIntStringToBigInt(invalid)	5,467,959	0.000182884
  getISO31661Alpha2CountryCodeSet()	108,364	0.009228138
  safeStructuredClone(record)	226,794	0.004409285
  safeStructuredClone(function)	47,082	0.021239342
  afterIdleFor(callback)	2,602,432	0.000384256

• Results vary by machine.

License

Apache-2.0