@strav/kernel 0.1.0

package/src/helpers/compose.ts

@@ -0,0 +1,104 @@
+/**
+ * Normalizes a constructor to satisfy TypeScript's mixin constraint.
+ *
+ * TypeScript requires mixin base classes to have a `new (...args: any[]) => any`
+ * constructor. This type widens any class constructor while preserving its
+ * instance type and static members.
+ *
+ * @see https://github.com/microsoft/TypeScript/issues/37142
+ *
+ * @example
+ * function myMixin<T extends NormalizeConstructor<typeof BaseModel>>(superclass: T) {
+ *   return class extends superclass {
+ *     greet() { return 'hello' }
+ *   }
+ * }
+ */
+export type NormalizeConstructor<T extends new (...args: any[]) => any> = {
+  new (...args: any[]): InstanceType<T>
+} & Omit<T, 'constructor'>
+
+interface MixinFunction<In, Out> {
+  (superclass: In): Out
+}
+
+/**
+ * Compose a class by applying mixins left-to-right.
+ *
+ * Eliminates deeply nested mixin syntax and provides full type safety
+ * for up to 8 mixins.
+ *
+ * @example
+ * import { compose } from '@stravigor/kernel/helpers'
+ * import { BaseModel } from '@stravigor/database/orm'
+ * import { billable } from '@stravigor/stripe'
+ *
+ * // Without compose (nested):
+ * class User extends billable(softDeletes(BaseModel)) { }
+ *
+ * // With compose (flat):
+ * class User extends compose(BaseModel, softDeletes, billable) { }
+ */
+export function compose<T extends new (...args: any[]) => any, A>(
+  superclass: T,
+  mixinA: MixinFunction<T, A>
+): A
+export function compose<T extends new (...args: any[]) => any, A, B>(
+  superclass: T,
+  mixinA: MixinFunction<T, A>,
+  mixinB: MixinFunction<A, B>
+): B
+export function compose<T extends new (...args: any[]) => any, A, B, C>(
+  superclass: T,
+  mixinA: MixinFunction<T, A>,
+  mixinB: MixinFunction<A, B>,
+  mixinC: MixinFunction<B, C>
+): C
+export function compose<T extends new (...args: any[]) => any, A, B, C, D>(
+  superclass: T,
+  mixinA: MixinFunction<T, A>,
+  mixinB: MixinFunction<A, B>,
+  mixinC: MixinFunction<B, C>,
+  mixinD: MixinFunction<C, D>
+): D
+export function compose<T extends new (...args: any[]) => any, A, B, C, D, E>(
+  superclass: T,
+  mixinA: MixinFunction<T, A>,
+  mixinB: MixinFunction<A, B>,
+  mixinC: MixinFunction<B, C>,
+  mixinD: MixinFunction<C, D>,
+  mixinE: MixinFunction<D, E>
+): E
+export function compose<T extends new (...args: any[]) => any, A, B, C, D, E, F>(
+  superclass: T,
+  mixinA: MixinFunction<T, A>,
+  mixinB: MixinFunction<A, B>,
+  mixinC: MixinFunction<B, C>,
+  mixinD: MixinFunction<C, D>,
+  mixinE: MixinFunction<D, E>,
+  mixinF: MixinFunction<E, F>
+): F
+export function compose<T extends new (...args: any[]) => any, A, B, C, D, E, F, G>(
+  superclass: T,
+  mixinA: MixinFunction<T, A>,
+  mixinB: MixinFunction<A, B>,
+  mixinC: MixinFunction<B, C>,
+  mixinD: MixinFunction<C, D>,
+  mixinE: MixinFunction<D, E>,
+  mixinF: MixinFunction<E, F>,
+  mixinG: MixinFunction<F, G>
+): G
+export function compose<T extends new (...args: any[]) => any, A, B, C, D, E, F, G, H>(
+  superclass: T,
+  mixinA: MixinFunction<T, A>,
+  mixinB: MixinFunction<A, B>,
+  mixinC: MixinFunction<B, C>,
+  mixinD: MixinFunction<C, D>,
+  mixinE: MixinFunction<D, E>,
+  mixinF: MixinFunction<E, F>,
+  mixinG: MixinFunction<F, G>,
+  mixinH: MixinFunction<G, H>
+): H
+export function compose(superclass: any, ...mixins: Function[]) {
+  return mixins.reduce((c, mixin) => mixin(c), superclass)
+}

package/src/helpers/crypto.ts

@@ -0,0 +1,4 @@
+/** Generate a random hex string of the given byte length. */
+export function randomHex(bytes: number): string {
+  return Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString('hex')
+}

package/src/helpers/env.ts

@@ -0,0 +1,50 @@
+/**
+ * Read an environment variable with an optional default.
+ *
+ * Bun auto-loads `.env`, so all variables are available via `process.env`.
+ *
+ * @example
+ * env('DB_HOST', '127.0.0.1')
+ * env('APP_KEY') // throws if not set and no default
+ */
+function env(key: string, defaultValue: string): string
+function env(key: string, defaultValue: null): string | null
+function env(key: string): string
+function env(key: string, defaultValue?: string | null): string | null {
+  const value = process.env[key]
+  if (value !== undefined) return value
+  if (defaultValue !== undefined) return defaultValue
+  throw new Error(`Environment variable "${key}" is not set`)
+}
+
+/** Read an environment variable as an integer. */
+env.int = (key: string, defaultValue?: number): number => {
+  const raw = process.env[key]
+  if (raw !== undefined) {
+    const parsed = parseInt(raw, 10)
+    if (!isNaN(parsed)) return parsed
+  }
+  if (defaultValue !== undefined) return defaultValue
+  throw new Error(`Environment variable "${key}" is not set or not a valid integer`)
+}
+
+/** Read an environment variable as a float. */
+env.float = (key: string, defaultValue?: number): number => {
+  const raw = process.env[key]
+  if (raw !== undefined) {
+    const parsed = parseFloat(raw)
+    if (!isNaN(parsed)) return parsed
+  }
+  if (defaultValue !== undefined) return defaultValue
+  throw new Error(`Environment variable "${key}" is not set or not a valid number`)
+}
+
+/** Read an environment variable as a boolean. Truthy: `'true'`, `'1'`, `'yes'`. */
+env.bool = (key: string, defaultValue?: boolean): boolean => {
+  const raw = process.env[key]
+  if (raw !== undefined) return ['true', '1', 'yes'].includes(raw.toLowerCase())
+  if (defaultValue !== undefined) return defaultValue
+  throw new Error(`Environment variable "${key}" is not set`)
+}
+
+export { env }

package/src/helpers/index.ts

@@ -0,0 +1,6 @@
+export { toSnakeCase, toCamelCase, toPascalCase } from './strings.ts'
+export { env } from './env.ts'
+export { randomHex } from './crypto.ts'
+export { compose } from './compose.ts'
+export type { NormalizeConstructor } from './compose.ts'
+export { ulid, isUlid } from './ulid.ts'

package/src/helpers/strings.ts

@@ -0,0 +1,67 @@
+/**
+ * Convert a camelCase or PascalCase string to snake_case.
+ *
+ * @example
+ * toSnakeCase('firstName')  // 'first_name'
+ * toSnakeCase('HTMLParser')  // 'html_parser'
+ * toSnakeCase('already_snake') // 'already_snake'
+ */
+export function toSnakeCase(str: string): string {
+  return str
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+    .replace(/([a-z\d])([A-Z])/g, '$1_$2')
+    .toLowerCase()
+}
+
+/**
+ * Convert a snake_case string to camelCase.
+ *
+ * @example
+ * toCamelCase('first_name')      // 'firstName'
+ * toCamelCase('created_at')      // 'createdAt'
+ * toCamelCase('reviewed_by_id')  // 'reviewedById'
+ * toCamelCase('id')              // 'id'
+ */
+export function toCamelCase(str: string): string {
+  return str.replace(/_([a-z\d])/g, (_, c) => c.toUpperCase())
+}
+
+/**
+ * Convert a snake_case or plain string to PascalCase.
+ *
+ * @example
+ * toPascalCase('user_role')   // 'UserRole'
+ * toPascalCase('user')        // 'User'
+ * toPascalCase('order_item')  // 'OrderItem'
+ */
+export function toPascalCase(str: string): string {
+  const camel = toCamelCase(str)
+  return camel.charAt(0).toUpperCase() + camel.slice(1)
+}
+
+/**
+ * Naively pluralize an English word.
+ *
+ * Handles common suffixes (s/x/z/ch/sh → es, consonant+y → ies).
+ * Not a full inflection library — adequate for code-gen route paths.
+ *
+ * @example
+ * pluralize('user')      // 'users'
+ * pluralize('category')  // 'categories'
+ * pluralize('status')    // 'statuses'
+ */
+export function pluralize(word: string): string {
+  if (
+    word.endsWith('s') ||
+    word.endsWith('x') ||
+    word.endsWith('z') ||
+    word.endsWith('ch') ||
+    word.endsWith('sh')
+  ) {
+    return word + 'es'
+  }
+  if (word.endsWith('y') && !/[aeiou]y$/.test(word)) {
+    return word.slice(0, -1) + 'ies'
+  }
+  return word + 's'
+}

package/src/helpers/ulid.ts

@@ -0,0 +1,28 @@
+import { ulid as generateUlid } from 'ulid'
+
+/**
+ * Generate a ULID (Universally Unique Lexicographically Sortable Identifier).
+ *
+ * ULIDs are 26-character strings that are:
+ * - Lexicographically sortable
+ * - Contain a timestamp component
+ * - Cryptographically secure random component
+ *
+ * @returns A new ULID string
+ */
+export function ulid(): string {
+  return generateUlid()
+}
+
+/**
+ * Check if a string is a valid ULID.
+ *
+ * @param value The string to check
+ * @returns true if the string is a valid ULID format
+ */
+export function isUlid(value: string): boolean {
+  // ULID is exactly 26 characters long and uses Crockford's base32
+  // Crockford's base32 excludes I, L, O, U to avoid confusion
+  const ulidRegex = /^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$/
+  return ulidRegex.test(value)
+}

package/src/i18n/defaults/en/validation.json

@@ -0,0 +1,20 @@
+{
+  "required": "This field is required",
+  "string": "Must be a string",
+  "integer": "Must be an integer",
+  "number": "Must be a number",
+  "boolean": "Must be a boolean",
+  "min": {
+    "number": "Must be at least :min",
+    "string": "Must be at least :min characters"
+  },
+  "max": {
+    "number": "Must be at most :max",
+    "string": "Must be at most :max characters"
+  },
+  "email": "Must be a valid email address",
+  "url": "Must be a valid URL",
+  "regex": "Invalid format",
+  "enum": "Must be one of: :values",
+  "array": "Must be an array"
+}

package/src/i18n/helpers.ts

@@ -0,0 +1,76 @@
+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,157 @@
+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,3 @@
+export { default as I18nManager } from './i18n_manager.ts'
+export { t, choice, locale, localeStorage } from './helpers.ts'
+export type { I18nConfig, Messages, LocaleDetection } from './types.ts'

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/index.ts

@@ -0,0 +1,11 @@
+export * from './core/index.ts'
+export * from './config/index.ts'
+export * from './events/index.ts'
+export * from './exceptions/index.ts'
+export * from './helpers/index.ts'
+export * from './encryption/index.ts'
+export * from './storage/index.ts'
+export * from './cache/index.ts'
+export * from './i18n/index.ts'
+export * from './logger/index.ts'
+export * from './providers/index.ts'

package/src/logger/index.ts

@@ -0,0 +1,5 @@
+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'