Skip to content
TomoriBot

Utils and Helpers

This is a current map of shared utility modules under src/utils/.

Folder Map

Section titled “Folder Map”
  • utils/async
  • utils/audio
  • utils/bridges
  • utils/cache
  • utils/chat
  • utils/compaction
  • utils/conditioning
  • utils/db
  • utils/discord
  • utils/documents
  • utils/embeddings
  • utils/image
  • utils/mcp
  • utils/media
  • utils/memory
  • utils/metrics
  • utils/misc
  • utils/novelai
  • utils/persona
  • utils/provider
  • utils/quota
  • utils/security
  • utils/storage
  • utils/teach
  • utils/text
  • utils/tools

High-Impact Modules

Section titled “High-Impact Modules”

utils/db

Section titled “utils/db”
  • client.ts: DB client wiring
  • initializeDatabase.ts: schema + seed startup runner
  • sqlSecurity.ts: query parameterisation helpers
  • sqlSplitter.ts: SQL file parsing utilities
  • ragAvailability.ts: pgvector / RAG feature detection
  • repositories/: 23 domain-owned Repository classes + index.ts (instance + type re-exports only). All SQL is inlined as private methods on each Repository class — no *ReadSql.ts / *WriteSql.ts sibling files exist. ErrorLogRepository is a thin shim used by logger.ts to insert into error_logs without creating a circular import. See docs/subsystems/database-schema.md for the full repository table and SQL convention.

utils/discord

Section titled “utils/discord”
  • commandLoader.ts: command discovery + localization wiring
  • commandRegistry.ts: runtime command maps used by handlers
  • interactionHelper.ts: compatibility barrel for grouped UI helpers in utils/discord/ui/; new code imports the owned UI module directly
  • streamOrchestrator.ts: public stream orchestration entry point backed by responsibility modules in utils/discord/stream/
  • webhookManager.ts: compatibility barrel for grouped webhook helpers in utils/discord/webhook/; new code imports the owned webhook module directly
  • embedHelper.ts, historyFetcher.ts, historyFormatter.ts

utils/text

Section titled “utils/text”
  • localizer.ts: locale auto-discovery + lookup
  • contextBuilder.ts: public structured context routing and native orchestration
  • context/: context-builder support modules for types, template/conditioning blocks, memories, RAG, and history/media helpers
  • contextTruncator.ts: token-budget truncation strategy
  • processors/regexUtils.ts: escapeRegExp
  • processors/mentionProcessor.ts: mention resolution, template variables, emoji normalization
  • processors/llmOutputProcessor.ts: LLM output cleaning, speaker-turn truncation
  • processors/chunkProcessor.ts: message chunking, sentence splitting
  • processors/formatters.ts: time formatting, text humanization, boolean display
  • processors/timeUtils.ts: reminder time parsing, lateness calculation
  • emojiHelper.ts, emojiPenalty.ts
  • timezoneHelper.ts, uncensor.ts, youTubeUrlCleaner.ts

utils/cache

Section titled “utils/cache”
  • tomoriStateCache.ts
  • userCache.ts
  • emojiStickerCache.ts
  • channelLlmCache.ts, channelLlmCacheStore.ts
  • channelWhitelistCache.ts
  • shortTermMemoryCache.ts
  • llmCache.ts
  • openrouterCapabilityCache.ts
  • geminiCapabilityCache.ts
  • novelaiCapabilityCache.ts
  • emergencyCacheClearer.ts: critical-memory cleanup for recoverable caches
  • lazy sync helpers (emojiLazySync.ts, stickerLazySync.ts)

utils/security

Section titled “utils/security”
  • secretsManager.ts: .env vs AWS Secrets Manager load path
  • keyManager.ts: encryption key version management
  • crypto.ts: encryption/decryption helpers
  • keyRotation.ts: rotation workflows
  • rateLimiter.ts: upload quota cleanup scheduler
  • safeDownload.ts: constrained external content download

utils/quota

Section titled “utils/quota”
  • imageQuotaManager.ts: per-user and server-wide image generation quotas
  • textQuotaManager.ts: per-user and server-wide text trigger quotas
  • videoQuotaManager.ts: per-user and server-wide video generation quotas

utils/provider

Section titled “utils/provider”
  • providerFactory.ts: provider auto-discovery and instance resolution

utils/mcp

Section titled “utils/mcp”
  • mcpManager.ts: MCP lifecycle
  • mcpExecutor.ts: MCP execution abstraction
  • mcpConfig.ts: MCP config loading
  • mcpUrlSecurity.ts: guild MCP URL parsing, DNS/IP validation, and SSRF hardening

utils/bridges

Section titled “utils/bridges”
  • bridgeUserId.ts: bridge ID and webhook username parsing utilities
  • matrix/: Matrix appservice bridge runtime
  • matrix/events.ts: appservice init and Matrix inbound event surface
  • matrix/stateSync.ts: Matrix link cache, typing state, reminder mention surface
  • matrix/userMapping.ts: Matrix display-name/ID maps and persona intent surface
  • matrix/rooms.ts: Matrix room join/config/encryption helpers
  • matrix/matrixManager.ts: thin Matrix public coordinator barrel

New code should use utils/bridges for generic bridge helpers and utils/bridges/matrix for Matrix runtime operations.

utils/image and utils/storage

Section titled “utils/image and utils/storage”
  • avatarHelper.ts, imageProcessor.ts, pngMetadata.ts
  • avatarStorage.ts for S3/public avatar URL support
  • charrefStorage.ts for NovelAI character reference storage (S3 in production, local filesystem in non-production)

utils/misc

Section titled “utils/misc”
  • logger.ts: structured logging facade
  • ioHelper.ts: filesystem traversal helpers
  • healthTracker.ts: runtime health signals used by /health

Usage Guidance

Section titled “Usage Guidance”
  • Prefer these shared modules over duplicating logic in commands/events.
  • For user-facing responses, always pair utility usage with localization via localizer().
  • For DB writes touching cached data, invalidate the affected caches in the same code path.