@stravigor/core 0.1.0

package/src/i18n/helpers.ts

@@ -0,0 +1,72 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import I18nManager from './i18n_manager.ts'
+import { translate, translateChoice, interpolate } from './translator.ts'
+
+/**
+ * Request-scoped locale storage.
+ * The i18n middleware sets the locale per-request via `localeStorage.run()`.
+ */
+export const localeStorage = new AsyncLocalStorage<string>()
+
+// Hardcoded English fallbacks for validation rules when i18n is not configured
+const VALIDATION_DEFAULTS: Record<string, string> = {
+  'validation.required': 'This field is required',
+  'validation.string': 'Must be a string',
+  'validation.integer': 'Must be an integer',
+  'validation.number': 'Must be a number',
+  'validation.boolean': 'Must be a boolean',
+  'validation.min.number': 'Must be at least :min',
+  'validation.min.string': 'Must be at least :min characters',
+  'validation.max.number': 'Must be at most :max',
+  'validation.max.string': 'Must be at most :max characters',
+  'validation.email': 'Must be a valid email address',
+  'validation.url': 'Must be a valid URL',
+  'validation.regex': 'Invalid format',
+  'validation.enum': 'Must be one of: :values',
+  'validation.array': 'Must be an array',
+}
+
+/**
+ * Get the current locale from the request context, or the default locale.
+ *
+ * @example
+ * locale()  // 'en'
+ */
+export function locale(): string {
+  return localeStorage.getStore() ?? I18nManager.config.default
+}
+
+/**
+ * Translate a key with optional replacements.
+ * Uses the current request locale (from AsyncLocalStorage).
+ *
+ * If i18n is not configured, returns English fallbacks for validation
+ * keys and the raw key for everything else.
+ *
+ * @example
+ * t('auth.failed')                           // "Invalid credentials"
+ * t('messages.welcome', { name: 'Alice' })   // "Welcome, Alice!"
+ */
+export function t(key: string, replacements?: Record<string, string | number>): string {
+  if (!I18nManager.isLoaded) {
+    // Fallback: return hardcoded English default or the key itself
+    const fallback = VALIDATION_DEFAULTS[key]
+    if (fallback) return replacements ? interpolate(fallback, replacements) : fallback
+    return key
+  }
+
+  return translate(locale(), key, replacements)
+}
+
+/**
+ * Pluralized translation based on count.
+ *
+ * @example
+ * choice('messages.apple', 1)  // "one apple"
+ * choice('messages.apple', 5)  // "5 apples"
+ */
+export function choice(key: string, count: number, replacements?: Record<string, string | number>): string {
+  if (!I18nManager.isLoaded) return key
+
+  return translateChoice(locale(), key, count, replacements)
+}

package/src/i18n/i18n_manager.ts

@@ -0,0 +1,155 @@
+import { resolve, join, basename } from 'node:path'
+import { readdirSync } from 'node:fs'
+import { inject } from '../core/inject.ts'
+import Configuration from '../config/configuration.ts'
+import { ConfigurationError } from '../exceptions/errors.ts'
+import { dotGet } from './translator.ts'
+import type { I18nConfig, Messages, LocaleDetection } from './types.ts'
+
+// Default English validation messages (loaded as base layer)
+import defaultValidation from './defaults/en/validation.json'
+
+/**
+ * Central i18n configuration hub.
+ *
+ * Resolved once via the DI container — reads the i18n config,
+ * loads translation files from disk, and provides key resolution.
+ *
+ * @example
+ * app.singleton(I18nManager)
+ * app.resolve(I18nManager)
+ * await I18nManager.load()
+ */
+@inject
+export default class I18nManager {
+  private static _config: I18nConfig
+  private static _translations = new Map<string, Messages>()
+  private static _loaded = false
+
+  constructor(config: Configuration) {
+    I18nManager._config = {
+      default: config.get('i18n.default', 'en') as string,
+      fallback: config.get('i18n.fallback', 'en') as string,
+      supported: config.get('i18n.supported', ['en']) as string[],
+      directory: config.get('i18n.directory', 'lang') as string,
+      detect: config.get('i18n.detect', ['header']) as LocaleDetection[],
+    }
+  }
+
+  static get config(): I18nConfig {
+    if (!I18nManager._config) {
+      throw new ConfigurationError('I18nManager not configured. Resolve it through the container first.')
+    }
+    return I18nManager._config
+  }
+
+  /** Whether translation files have been loaded. */
+  static get isLoaded(): boolean {
+    return I18nManager._loaded
+  }
+
+  /**
+   * Load all translation files from the configured directory.
+   * Merges built-in defaults as the base layer.
+   */
+  static async load(): Promise<void> {
+    // Load built-in defaults first
+    I18nManager.mergeMessages('en', { validation: defaultValidation as Messages })
+
+    // Scan lang/ directory
+    const langDir = resolve(I18nManager._config.directory)
+
+    let locales: string[]
+    try {
+      locales = readdirSync(langDir, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .map(d => d.name)
+    } catch {
+      // No lang directory — use defaults only
+      I18nManager._loaded = true
+      return
+    }
+
+    for (const locale of locales) {
+      const localeDir = join(langDir, locale)
+      let files: string[]
+      try {
+        files = readdirSync(localeDir).filter(f => f.endsWith('.json'))
+      } catch {
+        continue
+      }
+
+      for (const file of files) {
+        const namespace = basename(file, '.json')
+        const filePath = join(localeDir, file)
+        const content = await Bun.file(filePath).json()
+        I18nManager.mergeMessages(locale, { [namespace]: content as Messages })
+      }
+    }
+
+    I18nManager._loaded = true
+  }
+
+  /**
+   * Resolve a translation key for a specific locale.
+   * Tries the requested locale, then the fallback locale.
+   * Returns null if not found in either.
+   */
+  static resolve(locale: string, key: string): string | null {
+    // Try requested locale
+    const messages = I18nManager._translations.get(locale)
+    if (messages) {
+      const value = dotGet(messages, key)
+      if (typeof value === 'string') return value
+    }
+
+    // Try fallback locale
+    const fallback = I18nManager._config?.fallback ?? 'en'
+    if (locale !== fallback) {
+      const fallbackMessages = I18nManager._translations.get(fallback)
+      if (fallbackMessages) {
+        const value = dotGet(fallbackMessages, key)
+        if (typeof value === 'string') return value
+      }
+    }
+
+    return null
+  }
+
+  /** Register translations at runtime (useful for testing or dynamic loading). */
+  static register(locale: string, messages: Messages): void {
+    I18nManager.mergeMessages(locale, messages)
+  }
+
+  /** Reset all state (for testing). */
+  static reset(): void {
+    I18nManager._translations.clear()
+    I18nManager._loaded = false
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private static mergeMessages(locale: string, messages: Messages): void {
+    const existing = I18nManager._translations.get(locale) ?? {}
+    I18nManager._translations.set(locale, deepMerge(existing, messages))
+  }
+}
+
+function deepMerge(target: Messages, source: Messages): Messages {
+  const result = { ...target }
+  for (const [key, value] of Object.entries(source)) {
+    if (
+      typeof value === 'object' &&
+      value !== null &&
+      typeof result[key] === 'object' &&
+      result[key] !== null
+    ) {
+      result[key] = deepMerge(result[key] as Messages, value as Messages)
+    } else {
+      result[key] = value
+    }
+  }
+  return result
+}

package/src/i18n/index.ts

@@ -0,0 +1,4 @@
+export { default as I18nManager } from './i18n_manager.ts'
+export { t, choice, locale, localeStorage } from './helpers.ts'
+export { i18n } from './middleware.ts'
+export type { I18nConfig, Messages, LocaleDetection } from './types.ts'

package/src/i18n/middleware.ts

@@ -0,0 +1,90 @@
+import type Context from '../http/context.ts'
+import type { Next } from '../http/middleware.ts'
+import type { Middleware } from '../http/middleware.ts'
+import I18nManager from './i18n_manager.ts'
+import { localeStorage } from './helpers.ts'
+
+/**
+ * i18n middleware — detects the request locale and sets it for the
+ * duration of the request via `AsyncLocalStorage`.
+ *
+ * Detection strategies are tried in the order configured in `config/i18n.ts`.
+ *
+ * @example
+ * import { i18n } from '@stravigor/core/i18n'
+ * router.use(i18n())
+ */
+export function i18n(): Middleware {
+  return (ctx: Context, next: Next) => {
+    const detected = detectLocale(ctx)
+    return localeStorage.run(detected, () => next())
+  }
+}
+
+/**
+ * Detect locale from the request using configured strategies.
+ * Falls back to the default locale if no strategy matches.
+ */
+function detectLocale(ctx: Context): string {
+  const config = I18nManager.config
+  const supported = config.supported
+
+  for (const strategy of config.detect) {
+    switch (strategy) {
+      case 'query': {
+        const lang = ctx.query.get('lang') ?? ctx.query.get('locale')
+        if (lang && supported.includes(lang)) return lang
+        break
+      }
+      case 'cookie': {
+        const cookie = ctx.cookie('locale')
+        if (cookie && supported.includes(cookie)) return cookie
+        break
+      }
+      case 'header': {
+        const match = parseAcceptLanguage(
+          ctx.headers.get('accept-language'),
+          supported
+        )
+        if (match) return match
+        break
+      }
+    }
+  }
+
+  return config.default
+}
+
+/**
+ * Parse the Accept-Language header and return the best match
+ * against supported locales.
+ *
+ * @example
+ * parseAcceptLanguage('fr-FR,fr;q=0.9,en;q=0.8', ['en', 'fr'])  // 'fr'
+ */
+export function parseAcceptLanguage(
+  header: string | null,
+  supported: string[]
+): string | null {
+  if (!header) return null
+
+  // Parse entries like "fr-FR,fr;q=0.9,en-US;q=0.8,en;q=0.7"
+  const entries = header
+    .split(',')
+    .map(part => {
+      const [tag = '', ...rest] = part.trim().split(';')
+      const qPart = rest.find(r => r.trim().startsWith('q='))
+      const q = qPart ? parseFloat(qPart.trim().slice(2)) : 1.0
+      return { tag: tag.trim().toLowerCase(), q: Number.isNaN(q) ? 0 : q }
+    })
+    .sort((a, b) => b.q - a.q)
+
+  // Try exact match first, then base language (e.g. 'fr-FR' → 'fr')
+  for (const { tag } of entries) {
+    if (supported.includes(tag)) return tag
+    const base = tag.split('-')[0]!
+    if (supported.includes(base)) return base
+  }
+
+  return null
+}

package/src/i18n/translator.ts

@@ -0,0 +1,96 @@
+import I18nManager from './i18n_manager.ts'
+import type { Messages } from './types.ts'
+
+/**
+ * Resolve a dot-notated key from a nested messages object.
+ *
+ * @example
+ * dotGet({ auth: { failed: 'Invalid' } }, 'auth.failed')  // 'Invalid'
+ */
+export function dotGet(messages: Messages, key: string): string | Messages | undefined {
+  const parts = key.split('.')
+  let current: string | Messages | undefined = messages
+
+  for (const part of parts) {
+    if (typeof current !== 'object' || current === null) return undefined
+    current = (current as Messages)[part]
+  }
+
+  return current
+}
+
+/**
+ * Replace `:key` placeholders with values from the replacements object.
+ *
+ * @example
+ * interpolate('Hello, :name!', { name: 'Alice' })  // 'Hello, Alice!'
+ */
+export function interpolate(
+  message: string,
+  replacements: Record<string, string | number>
+): string {
+  let result = message
+  for (const [key, value] of Object.entries(replacements)) {
+    result = result.replaceAll(`:${key}`, String(value))
+  }
+  return result
+}
+
+/**
+ * Resolve a translation key and interpolate replacements.
+ * Falls back to the fallback locale, then returns the key itself.
+ */
+export function translate(
+  locale: string,
+  key: string,
+  replacements?: Record<string, string | number>
+): string {
+  const raw = I18nManager.resolve(locale, key)
+  if (raw === null) return key
+
+  return replacements ? interpolate(raw, replacements) : raw
+}
+
+// Plural category order used by Intl.PluralRules
+const PLURAL_CATEGORIES = ['zero', 'one', 'two', 'few', 'many', 'other'] as const
+
+/**
+ * Pluralize a translation based on count.
+ *
+ * The translation value uses `|` to separate plural forms:
+ * - 2 forms: `"one apple|:count apples"` → `Intl.PluralRules` picks one vs other
+ * - 6 forms: mapped to `zero|one|two|few|many|other`
+ *
+ * `:count` is automatically added to replacements.
+ */
+export function translateChoice(
+  locale: string,
+  key: string,
+  count: number,
+  replacements?: Record<string, string | number>
+): string {
+  const raw = I18nManager.resolve(locale, key)
+  if (raw === null) return key
+
+  const segments = raw.split('|')
+  const merged = { count, ...replacements }
+
+  let chosen: string
+
+  if (segments.length === 1) {
+    chosen = segments[0]!
+  } else if (segments.length === 2) {
+    // Simple singular/plural
+    const rules = new Intl.PluralRules(locale)
+    const category = rules.select(count)
+    chosen = category === 'one' ? segments[0]! : segments[1]!
+  } else {
+    // Map to plural categories
+    const rules = new Intl.PluralRules(locale)
+    const category = rules.select(count)
+    const index = PLURAL_CATEGORIES.indexOf(category)
+    chosen = segments[Math.min(index, segments.length - 1)]!
+  }
+
+  return interpolate(chosen.trim(), merged)
+}

package/src/i18n/types.ts

@@ -0,0 +1,17 @@
+export interface I18nConfig {
+  /** Default locale, e.g. 'en'. */
+  default: string
+  /** Fallback locale when a key is missing in the current locale. */
+  fallback: string
+  /** List of supported locale codes. */
+  supported: string[]
+  /** Path to the lang/ directory (relative to cwd). */
+  directory: string
+  /** Locale detection strategies, tried in order. */
+  detect: LocaleDetection[]
+}
+
+export type LocaleDetection = 'header' | 'cookie' | 'query'
+
+/** Nested translation messages — leaf values are strings. */
+export type Messages = { [key: string]: string | Messages }

package/src/logger/index.ts

@@ -0,0 +1,6 @@
+export { default } from './logger.ts'
+export { default as Logger } from './logger.ts'
+export { LogSink, type SinkConfig, type LogLevel } from './sinks/sink.ts'
+export { ConsoleSink, type ConsoleSinkConfig } from './sinks/console_sink.ts'
+export { FileSink, type FileSinkConfig } from './sinks/file_sink.ts'
+export { requestLogger } from './request_logger.ts'

package/src/logger/logger.ts

@@ -0,0 +1,100 @@
+import pino from 'pino'
+import Configuration from '../config/configuration.ts'
+import { inject } from '../core/inject.ts'
+import { LogSink, type SinkConfig } from './sinks/sink'
+import { ConsoleSink } from './sinks/console_sink'
+import { FileSink } from './sinks/file_sink'
+
+type SinkConstructor = new (config: SinkConfig) => LogSink
+
+/**
+ * Maps sink names used in `config/logging.ts` to their implementing classes.
+ * Register new sink types here so the Logger can instantiate them from config.
+ */
+const sinkRegistry: Record<string, SinkConstructor> = {
+  console: ConsoleSink,
+  file: FileSink,
+}
+
+/**
+ * Structured logger backed by pino with configurable sinks.
+ *
+ * Sinks (console, file, …) are declared in `config/logging.ts` and combined
+ * at construction time via `pino.multistream`. Each sink can define its own
+ * minimum log level independently of the global level.
+ *
+ * @example
+ * // Resolve via DI (Configuration is injected automatically):
+ * container.singleton(Logger)
+ * const logger = container.resolve(Logger)
+ *
+ * logger.info('server started', { port: 3000 })
+ * logger.error('request failed', { statusCode: 500, path: '/api/users' })
+ */
+@inject
+export default class Logger {
+  private pino: pino.Logger
+
+  constructor(protected config: Configuration) {
+    const sinks = this.buildSinks()
+
+    const streams = sinks.map(sink => ({
+      stream: sink.createStream(),
+      level: sink.level as pino.Level,
+    }))
+
+    const level = this.config.get('logging.level', 'info') as string satisfies string
+
+    this.pino = streams.length > 0 ? pino({ level }, pino.multistream(streams)) : pino({ level })
+  }
+
+  /** Log at `trace` level (most verbose). */
+  trace(msg: string, context?: Record<string, unknown>): void {
+    context ? this.pino.trace(context, msg) : this.pino.trace(msg)
+  }
+
+  /** Log at `debug` level. */
+  debug(msg: string, context?: Record<string, unknown>): void {
+    context ? this.pino.debug(context, msg) : this.pino.debug(msg)
+  }
+
+  /** Log at `info` level. */
+  info(msg: string, context?: Record<string, unknown>): void {
+    context ? this.pino.info(context, msg) : this.pino.info(msg)
+  }
+
+  /** Log at `warn` level. */
+  warn(msg: string, context?: Record<string, unknown>): void {
+    context ? this.pino.warn(context, msg) : this.pino.warn(msg)
+  }
+
+  /** Log at `error` level. */
+  error(msg: string, context?: Record<string, unknown>): void {
+    context ? this.pino.error(context, msg) : this.pino.error(msg)
+  }
+
+  /** Log at `fatal` level (most severe). */
+  fatal(msg: string, context?: Record<string, unknown>): void {
+    context ? this.pino.fatal(context, msg) : this.pino.fatal(msg)
+  }
+
+  /**
+   * Read the `logging.sinks` configuration and instantiate every enabled sink
+   * whose name matches an entry in {@link sinkRegistry}.
+   */
+  private buildSinks(): LogSink[] {
+    const sinks: LogSink[] = []
+    const sinksConfig = this.config.get('logging.sinks', {}) as Record<string, SinkConfig>
+
+    for (const [name, sinkConfig] of Object.entries(sinksConfig)) {
+      if (!sinkConfig.enabled) continue
+
+      const SinkClass = sinkRegistry[name]
+      if (SinkClass) {
+        sinks.push(new SinkClass(sinkConfig))
+      }
+    }
+
+    return sinks
+  }
+}

package/src/logger/request_logger.ts

@@ -0,0 +1,19 @@
+import type { Middleware } from '../http/middleware.ts'
+import type Logger from './logger.ts'
+
+export function requestLogger(logger: Logger): Middleware {
+  return async (ctx, next) => {
+    const start = performance.now()
+    const response = await next()
+    const duration = Math.round(performance.now() - start)
+
+    logger.info(`${ctx.method} ${ctx.path} ${response.status} ${duration}ms`, {
+      method: ctx.method,
+      path: ctx.path,
+      status: response.status,
+      duration,
+    })
+
+    return response
+  }
+}

package/src/logger/sinks/console_sink.ts

@@ -0,0 +1,24 @@
+import build from 'pino-pretty'
+import { LogSink, type SinkConfig } from './sink'
+
+/** Configuration specific to the console sink. */
+export interface ConsoleSinkConfig extends SinkConfig {
+  /** Enable ANSI colour output. Defaults to `true`. */
+  colorize?: boolean
+}
+
+/**
+ * Log sink that writes human-readable output to stdout via `pino-pretty`.
+ *
+ * Intended for local development; for structured JSON output in production
+ * consider disabling this sink and using the file sink instead.
+ */
+export class ConsoleSink extends LogSink {
+  createStream() {
+    const config = this.config as ConsoleSinkConfig
+
+    return build({
+      colorize: config.colorize ?? true,
+    })
+  }
+}

package/src/logger/sinks/file_sink.ts

@@ -0,0 +1,24 @@
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import pino from 'pino'
+import { LogSink, type SinkConfig } from './sink'
+
+/** Configuration specific to the file sink. */
+export interface FileSinkConfig extends SinkConfig {
+  /** Path to the log file. Parent directories are created automatically. */
+  path: string
+}
+
+/**
+ * Log sink that writes structured JSON to a file using pino's optimised
+ * {@link pino.destination | SonicBoom} writer with asynchronous flushing.
+ */
+export class FileSink extends LogSink {
+  createStream() {
+    const { path } = this.config as FileSinkConfig
+
+    mkdirSync(dirname(path), { recursive: true })
+
+    return pino.destination({ dest: path, sync: false })
+  }
+}

package/src/logger/sinks/sink.ts

@@ -0,0 +1,36 @@
+import type { DestinationStream } from 'pino'
+
+/** Supported log severity levels, from most to least verbose. */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent'
+
+/** Configuration object for a single log sink. */
+export interface SinkConfig {
+  /** Whether this sink is active. Disabled sinks are skipped by the Logger. */
+  enabled: boolean
+  /** Minimum severity level this sink will accept. Defaults to `"info"`. */
+  level?: LogLevel
+  [key: string]: unknown
+}
+
+/**
+ * Abstract base class for log sinks.
+ *
+ * Subclasses implement {@link createStream} to provide a writable destination
+ * (stdout, file, network, etc.) that the Logger combines via pino multistream.
+ *
+ * To add a new sink:
+ * 1. Extend this class and implement `createStream()`.
+ * 2. Register the class in the `sinkRegistry` inside `logger.ts`.
+ * 3. Add a corresponding section in `config/logging.ts`.
+ */
+export abstract class LogSink {
+  constructor(protected config: SinkConfig) {}
+
+  /** Create the writable destination stream for this sink. */
+  abstract createStream(): DestinationStream
+
+  /** Minimum log level for this sink. Defaults to `"info"` when not configured. */
+  get level(): LogLevel {
+    return this.config.level ?? 'info'
+  }
+}