chore: couple new methods

Author: jortsupetterson

README.md

@@ -12,6 +12,7 @@ Shared TypeScript utilities for removing repeated code across Sovereignbase code
 - 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
@@ -77,6 +78,8 @@ if (result[0]) {
 }
 ```
 
+Attempts a structured clone and returns a tuple instead of throwing on unsupported values.
+
 ### `getISO31661Alpha2CountryCodeSet()`
 
 ```ts
@@ -93,32 +96,45 @@ function epicFunction1(countryCode: ISO31661Alpha2) {
 }
 ```
 
-Attempts a structured clone and returns a tuple instead of throwing on unsupported values.
+Returns a fresh `Set` containing all supported ISO 3166-1 alpha-2 country codes.
+
+### `browserHasSovereignbaseDependencies()`
+
+```ts
+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.
 
 ## Tests
 
 - Latest local `npm run test` run passed on Node `v22.14.0`.
-- Node unit suite: `5/5` passed.
+- Node unit suite: `9/9` passed.
 - Node integration suite: `2/2` passed.
 - Coverage: `100%` statements, branches, functions, and lines.
-- Runtime E2E: Node ESM `9/9` passed.
-- Runtime E2E: Node CJS `9/9` passed.
-- Runtime E2E: Bun ESM `9/9` passed.
-- Runtime E2E: Bun CJS `9/9` passed.
-- Runtime E2E: Deno ESM `9/9` passed.
-- Runtime E2E: Cloudflare Workers ESM `9/9` passed.
-- Runtime E2E: Edge Runtime ESM `9/9` passed.
+- Runtime E2E: Node ESM `11/11` passed.
+- Runtime E2E: Node CJS `11/11` passed.
+- Runtime E2E: Bun ESM `11/11` passed.
+- Runtime E2E: Bun CJS `11/11` passed.
+- Runtime E2E: Deno ESM `11/11` passed.
+- Runtime E2E: Cloudflare Workers ESM `11/11` passed.
+- Runtime E2E: Edge Runtime ESM `11/11` 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`.
-- `prototype(record)`: `8,060,210 ops/sec` (`248.1 ms`).
-- `prototype(url)`: `3,624,304 ops/sec` (`551.8 ms`).
-- `isUuidV7(valid)`: `3,575,658 ops/sec` (`279.7 ms`).
-- `isUuidV7(invalid)`: `4,184,715 ops/sec` (`239.0 ms`).
-- `safeStructuredClone(record)`: `110,503 ops/sec` (`2262.4 ms`).
-- `safeStructuredClone(function)`: `28,112 ops/sec` (`8893.1 ms`).
+- `prototype(record)`: `4,882,423 ops/sec` (`409.6 ms`).
+- `prototype(url)`: `2,626,656 ops/sec` (`761.4 ms`).
+- `isUuidV7(valid)`: `2,366,821 ops/sec` (`422.5 ms`).
+- `isUuidV7(invalid)`: `2,970,958 ops/sec` (`336.6 ms`).
+- `getISO31661Alpha2CountryCodeSet()`: `35,059 ops/sec` (`1426.2 ms`).
+- `safeStructuredClone(record)`: `57,335 ops/sec` (`4360.4 ms`).
+- `safeStructuredClone(function)`: `12,678 ops/sec` (`19718.8 ms`).
 - Results vary by machine.
 
 ## License

benchmark/bench.js

@@ -1,6 +1,11 @@
 import { performance } from 'node:perf_hooks'
 
-import { isUuidV7, prototype, safeStructuredClone } from '../dist/index.js'
+import {
+  getISO31661Alpha2CountryCodeSet,
+  isUuidV7,
+  prototype,
+  safeStructuredClone,
+} from '../dist/index.js'
 
 const validUuidV7 = '018f0d1e-6c82-7d4b-91c1-8a7b5e2f4a10'
 const invalidUuid = '550e8400-e29b-41d4-a716-446655440000'
@@ -33,6 +38,9 @@ const results = [
   benchmark('prototype(url)', 2_000_000, () => prototype(urlValue)),
   benchmark('isUuidV7(valid)', 1_000_000, () => isUuidV7(validUuidV7)),
   benchmark('isUuidV7(invalid)', 1_000_000, () => isUuidV7(invalidUuid)),
+  benchmark('getISO31661Alpha2CountryCodeSet()', 50_000, () =>
+    getISO31661Alpha2CountryCodeSet()
+  ),
   benchmark('safeStructuredClone(record)', 250_000, () =>
     safeStructuredClone(cloneValue)
   ),

src/ISO31661Alpha2/index.ts

@@ -1,3 +1,6 @@
+/**
+ * Represents an ISO 3166-1 alpha-2 country code.
+ */
 export type ISO31661Alpha2 =
   | "AF"
   | "AX"
@@ -249,6 +252,11 @@ export type ISO31661Alpha2 =
   | "ZM"
   | "ZW";
 
+/**
+ * Returns a new set containing every supported ISO 3166-1 alpha-2 country code.
+ *
+ * @returns A fresh `Set` of uppercase two-character country codes.
+ */
 export function getISO31661Alpha2CountryCodeSet(): Set<ISO31661Alpha2> {
   return new Set([
     "AF",

…rowserHasSovereignbaseDepencies/index.ts …serHasSovereignbaseDependencies/index.tssrc/browserHasSovereignbaseDepencies/index.ts renamed to src/browserHasSovereignbaseDependencies/index.ts src/browserHasSovereignbaseDepencies/index.ts renamed to src/browserHasSovereignbaseDependencies/index.ts

@@ -1,4 +1,15 @@
-export async function browserHasSovereignbaseDepencies(): Promise<boolean> {
+/**
+ * Checks whether the current browser environment exposes the APIs required by
+ * Sovereignbase browser features.
+ *
+ * The check requires a secure browser context plus storage, worker,
+ * notifications, Web Crypto, and WebAuthn platform authenticator support. It
+ * resolves to `false` in non-browser runtimes and unsupported browsers.
+ *
+ * @returns A promise that resolves to `true` when the required browser
+ * dependencies are available; otherwise, `false`.
+ */
+export async function browserHasSovereignbaseDependencies(): Promise<boolean> {
   return (
     typeof window !== 'undefined' &&
     window.isSecureContext &&

src/index.ts

@@ -5,4 +5,4 @@ export {
   type ISO31661Alpha2,
   getISO31661Alpha2CountryCodeSet,
 } from './ISO31661Alpha2/index.js'
-export { browserHasSovereignbaseDepencies } from './browserHasSovereignbaseDepencies/index.js'
+export { browserHasSovereignbaseDependencies } from './browserHasSovereignbaseDependencies/index.js'

test/e2e/shared/suite.mjs

@@ -42,7 +42,13 @@ export async function runUtilsSuite(api, options = {}) {
   const runtimeGlobals = options.runtimeGlobals ?? globalThis
   const results = { label, ok: true, errors: [], tests: [] }
 
-  const { prototype, isUuidV7, safeStructuredClone } = api
+  const {
+    browserHasSovereignbaseDependencies,
+    getISO31661Alpha2CountryCodeSet,
+    prototype,
+    isUuidV7,
+    safeStructuredClone,
+  } = api
 
   function assert(condition, message) {
     if (!condition) throw new Error(message || 'assertion failed')
@@ -90,6 +96,14 @@ export async function runUtilsSuite(api, options = {}) {
   }
 
   await runTest('exports shape', () => {
+    assert(
+      typeof browserHasSovereignbaseDependencies === 'function',
+      'browserHasSovereignbaseDependencies export missing'
+    )
+    assert(
+      typeof getISO31661Alpha2CountryCodeSet === 'function',
+      'getISO31661Alpha2CountryCodeSet export missing'
+    )
     assert(typeof prototype === 'function', 'prototype export missing')
     assert(typeof isUuidV7 === 'function', 'isUuidV7 export missing')
     assert(
@@ -257,6 +271,35 @@ export async function runUtilsSuite(api, options = {}) {
     }
   )
 
+  await runTest(
+    'getISO31661Alpha2CountryCodeSet returns a fresh set of country codes',
+    () => {
+      const first = getISO31661Alpha2CountryCodeSet()
+      const second = getISO31661Alpha2CountryCodeSet()
+
+      assertEqual(Object.prototype.toString.call(first), '[object Set]')
+      assertEqual(first.size, 249)
+      assertEqual(first.has('FI'), true)
+      assertEqual(first.has('US'), true)
+      assertEqual(first.has('XX'), false)
+      assert(first !== second, 'expected a fresh Set per call')
+      assertEqual([...first].join(','), [...second].join(','))
+    }
+  )
+
+  await runTest(
+    'browserHasSovereignbaseDependencies reports runtime support',
+    async () => {
+      const supported = await browserHasSovereignbaseDependencies()
+
+      assertEqual(typeof supported, 'boolean')
+
+      if (typeof runtimeGlobals.window === 'undefined') {
+        assertEqual(supported, false)
+      }
+    }
+  )
+
   return results
 }
 

test/integration/integration.test.js

@@ -9,18 +9,22 @@ const cjsApi = require('../../dist/index.cjs')
 
 test('esm and cjs entrypoints expose the same runtime API', () => {
   assert.deepEqual(Object.keys(esmApi).sort(), [
+    'browserHasSovereignbaseDependencies',
+    'getISO31661Alpha2CountryCodeSet',
     'isUuidV7',
     'prototype',
     'safeStructuredClone',
   ])
   assert.deepEqual(Object.keys(cjsApi).sort(), [
+    'browserHasSovereignbaseDependencies',
+    'getISO31661Alpha2CountryCodeSet',
     'isUuidV7',
     'prototype',
     'safeStructuredClone',
   ])
 })
 
-test('esm and cjs entrypoints behave the same', () => {
+test('esm and cjs entrypoints behave the same', async () => {
   const values = [
     null,
     { ok: true },
@@ -60,4 +64,17 @@ test('esm and cjs entrypoints behave the same', () => {
     cjsApi.safeStructuredClone(() => {}),
     [false]
   )
+
+  const esmCountryCodes = esmApi.getISO31661Alpha2CountryCodeSet()
+  const cjsCountryCodes = cjsApi.getISO31661Alpha2CountryCodeSet()
+
+  assert.equal(esmCountryCodes.size, cjsCountryCodes.size)
+  assert.equal(esmCountryCodes.has('FI'), cjsCountryCodes.has('FI'))
+  assert.equal(esmCountryCodes.has('US'), cjsCountryCodes.has('US'))
+  assert.equal(esmCountryCodes.has('XX'), cjsCountryCodes.has('XX'))
+
+  assert.equal(
+    await esmApi.browserHasSovereignbaseDependencies(),
+    await cjsApi.browserHasSovereignbaseDependencies()
+  )
 })