Internal packages: logging, utils, and control flow

internal  →  libraries  →  apps

import Logger from '@nostrwatch/logger'

const log = new Logger('my-module', 'INFO')

log.info('relay connected')
// 2026-03-04T20:00:00.000Z [my-module] info: relay connected

log.debug('processing event')
// (no output — debug is below the INFO threshold)

log.warn('relay slow to respond')
// 2026-03-04T20:00:01.000Z [my-module] warn: relay slow to respond

class Logger {
  constructor(name: string, log_level?: string, split_logs?: boolean)
  fatal(message: any): void
  error(message: any): void
  err(message: any): void     // alias for error()
  warn(message: any): void
  info(message: any): void
  debug(message: any): void
}

DEBUG=my-module node index.js

import {nsecToHex, tryNsecToHex} from '@nostrwatch/utils'
import {shuffleArray, chunkArray} from '@nostrwatch/utils'
import {isBrowser} from '@nostrwatch/utils'

// Convert an nsec private key to hex (throws on invalid input)
const hexKey = nsecToHex('nsec1...')

// Safe version — returns empty string on failure
const safeHex = tryNsecToHex(process.env.NOSTR_KEY)

// Shuffle and chunk an array
const relays = ['wss://relay.damus.io', 'wss://nos.lol']
chunkArray(relays, 10) // => [['wss://relay.damus.io', 'wss://nos.lol']]

// Detect runtime environment
if (isBrowser()) {
  console.log('running in browser')
}

function nsecToBytes(key: string): Uint8Array
function nsecToHex(key: string): string
function tryNsecToHex(key: string | undefined): string

interface EventSigner {
  pubkey: string
  sign(event: UnsignedEvent): VerifiedEvent
}

function createSigner(key: string): EventSigner

function shuffleArray<T>(array: T[]): void
function chunkArray<T>(arr: T[], chunkSize: number): T[][]

function parseUrl(url: string): URL | null
function normalizeUrl(url: string): string

function isBrowser(): boolean

import {NocapdQueue, RetryManager} from '@nostrwatch/controlflow'

// Initialize a named BullMQ queue
const {$Queue, $QueueEvents, Worker} = NocapdQueue('my-worker')

// Add a relay-check job to the queue
await $Queue.add('check', {url: 'wss://relay.damus.io'})

// Process jobs in a worker
new Worker('my-worker', async (job) => {
  console.log('Checking:', job.data.url)
  // run your check here
})

class RetryManager {
  constructor(caller: string, config?: RetryConfig, rcache?: RelayCache)
  cacheId(url: string): string
  expiry(retries: number | null): number
  getRetries(url: string): Promise<number | null>
  getExpiry(url: string): Promise<number>
  setRetries(url: string, success: boolean): Promise<string | null>
}

import {RelaySeeder} from '@nostrwatch/seed'

const seeder = new RelaySeeder({
  interval: 3600000, // re-seed every hour
  sources: ['config', 'static', 'api'],
  options: {
    allowedNetworks: ['clearnet'],
    config: ['wss://relay.damus.io', 'wss://nos.lol'],
    static: {path: './relays.yaml'},
    api: {rest_api: 'https://api.nostr.watch/v1'}
  }
})

await seeder.start()

const relays = seeder.getRelays()
console.log(`Seeded ${relays.length} relays`)
// Seeded 247 relays