@strav/kernel 0.1.0

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@strav/kernel",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Foundation of the Strav framework — application lifecycle, IoC container, configuration, events, and core utilities",
+  "license": "MIT",
+  "keywords": [
+    "bun",
+    "framework",
+    "typescript",
+    "strav"
+  ],
+  "files": [
+    "src/",
+    "package.json",
+    "tsconfig.json",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./core": "./src/core/index.ts",
+    "./core/*": "./src/core/*.ts",
+    "./config": "./src/config/index.ts",
+    "./config/*": "./src/config/*.ts",
+    "./events": "./src/events/index.ts",
+    "./events/*": "./src/events/*.ts",
+    "./exceptions": "./src/exceptions/index.ts",
+    "./exceptions/*": "./src/exceptions/*.ts",
+    "./helpers": "./src/helpers/index.ts",
+    "./helpers/*": "./src/helpers/*.ts",
+    "./encryption": "./src/encryption/index.ts",
+    "./encryption/*": "./src/encryption/*.ts",
+    "./storage": "./src/storage/index.ts",
+    "./storage/*": "./src/storage/*.ts",
+    "./cache": "./src/cache/index.ts",
+    "./cache/*": "./src/cache/*.ts",
+    "./i18n": "./src/i18n/index.ts",
+    "./i18n/*": "./src/i18n/*.ts",
+    "./logger": "./src/logger/index.ts",
+    "./logger/*": "./src/logger/*.ts",
+    "./providers": "./src/providers/index.ts",
+    "./providers/*": "./src/providers/*.ts"
+  },
+  "dependencies": {
+    "@types/luxon": "^3.7.1",
+    "luxon": "^3.7.2",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "reflect-metadata": "^0.2.2",
+    "ulid": "^3.0.2"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.9"
+  }
+}

package/src/cache/cache_manager.ts

@@ -0,0 +1,60 @@
+import { inject } from '../core/inject.ts'
+import { ConfigurationError } from '../exceptions/errors.ts'
+import Configuration from '../config/configuration.ts'
+import { MemoryCacheStore } from './memory_store.ts'
+import type { CacheStore, CacheConfig } from './cache_store.ts'
+
+/**
+ * Central cache configuration hub.
+ *
+ * Resolved once via the DI container — reads the cache config
+ * and initializes the appropriate store driver.
+ *
+ * @example
+ * app.singleton(CacheManager)
+ * app.resolve(CacheManager)
+ *
+ * // Plug in a custom store (e.g., Redis)
+ * CacheManager.useStore(new MyRedisStore())
+ */
+@inject
+export default class CacheManager {
+  private static _store: CacheStore
+  private static _config: CacheConfig
+
+  constructor(config: Configuration) {
+    CacheManager._config = {
+      default: 'memory',
+      prefix: '',
+      ttl: 3600,
+      ...(config.get('cache', {}) as object),
+    }
+
+    const driver = CacheManager._config.default
+    if (driver === 'memory') {
+      CacheManager._store = new MemoryCacheStore()
+    } else {
+      throw new ConfigurationError(
+        `Unknown cache driver: ${driver}. Use CacheManager.useStore() for custom drivers.`
+      )
+    }
+  }
+
+  static get store(): CacheStore {
+    if (!CacheManager._store) {
+      throw new ConfigurationError(
+        'CacheManager not configured. Resolve it through the container first.'
+      )
+    }
+    return CacheManager._store
+  }
+
+  static get config(): CacheConfig {
+    return CacheManager._config
+  }
+
+  /** Swap the cache store at runtime (e.g., for testing or a custom Redis store). */
+  static useStore(store: CacheStore): void {
+    CacheManager._store = store
+  }
+}

package/src/cache/cache_store.ts

@@ -0,0 +1,31 @@
+/**
+ * Pluggable cache storage backend.
+ *
+ * Implement this interface to use Redis, database, or other stores.
+ * The default in-memory implementation uses a Map with lazy TTL eviction.
+ */
+export interface CacheStore {
+  /** Retrieve a cached value. Returns `null` if the key doesn't exist or has expired. */
+  get<T = unknown>(key: string): Promise<T | null>
+
+  /** Store a value with optional TTL in seconds. Omit TTL for no expiry. */
+  set(key: string, value: unknown, ttl?: number): Promise<void>
+
+  /** Check if a key exists and is not expired. */
+  has(key: string): Promise<boolean>
+
+  /** Remove a single key from the cache. */
+  forget(key: string): Promise<void>
+
+  /** Remove all entries from the cache. */
+  flush(): Promise<void>
+}
+
+export interface CacheConfig {
+  /** Cache driver name. @default 'memory' */
+  default: string
+  /** Key prefix applied to all cache operations. @default '' */
+  prefix: string
+  /** Default TTL in seconds when none is specified. @default 3600 */
+  ttl: number
+}

package/src/cache/helpers.ts

@@ -0,0 +1,74 @@
+import CacheManager from './cache_manager.ts'
+
+function prefixed(key: string): string {
+  return CacheManager.config.prefix + key
+}
+
+/**
+ * Cache helper object — the primary API for cache-aside operations.
+ *
+ * All methods delegate to `CacheManager.store` with the configured prefix.
+ *
+ * @example
+ * import { cache } from '@stravigor/kernel/cache'
+ *
+ * const user = await cache.remember(`user:${id}`, 300, () => User.find(id))
+ * await cache.forget(`user:${id}`)
+ */
+export const cache = {
+  /** Retrieve a cached value. */
+  async get<T = unknown>(key: string): Promise<T | null> {
+    return CacheManager.store.get<T>(prefixed(key))
+  },
+
+  /** Store a value with optional TTL in seconds. Falls back to config default. */
+  async set(key: string, value: unknown, ttl?: number): Promise<void> {
+    return CacheManager.store.set(prefixed(key), value, ttl ?? CacheManager.config.ttl)
+  },
+
+  /** Check if a key exists and is not expired. */
+  async has(key: string): Promise<boolean> {
+    return CacheManager.store.has(prefixed(key))
+  },
+
+  /** Remove a cached value. */
+  async forget(key: string): Promise<void> {
+    return CacheManager.store.forget(prefixed(key))
+  },
+
+  /** Clear all cached values. */
+  async flush(): Promise<void> {
+    return CacheManager.store.flush()
+  },
+
+  /**
+   * Cache-aside: return cached value or execute factory and cache the result.
+   *
+   * @example
+   * const user = await cache.remember(`user:${id}`, 300, () => User.find(id))
+   * const stats = await cache.remember('stats', 60, async () => ({
+   *   users: await User.count(),
+   *   projects: await Project.count(),
+   * }))
+   */
+  async remember<T>(key: string, ttl: number, factory: () => T | Promise<T>): Promise<T> {
+    const pk = prefixed(key)
+    const cached = await CacheManager.store.get<T>(pk)
+    if (cached !== null) return cached
+
+    const value = await factory()
+    await CacheManager.store.set(pk, value, ttl)
+    return value
+  },
+
+  /** Cache-aside with no expiry. */
+  async rememberForever<T>(key: string, factory: () => T | Promise<T>): Promise<T> {
+    const pk = prefixed(key)
+    const cached = await CacheManager.store.get<T>(pk)
+    if (cached !== null) return cached
+
+    const value = await factory()
+    await CacheManager.store.set(pk, value)
+    return value
+  },
+}

package/src/cache/index.ts

@@ -0,0 +1,4 @@
+export { default as CacheManager } from './cache_manager.ts'
+export { MemoryCacheStore } from './memory_store.ts'
+export { cache } from './helpers.ts'
+export type { CacheStore, CacheConfig } from './cache_store.ts'

package/src/cache/memory_store.ts

@@ -0,0 +1,63 @@
+import type { CacheStore } from './cache_store.ts'
+
+interface CacheEntry {
+  value: unknown
+  expiresAt: number | null // null = no expiry
+}
+
+/**
+ * In-memory cache store using a Map with lazy TTL eviction.
+ * Suitable for single-process deployments.
+ */
+export class MemoryCacheStore implements CacheStore {
+  private entries = new Map<string, CacheEntry>()
+
+  async get<T = unknown>(key: string): Promise<T | null> {
+    const entry = this.entries.get(key)
+    if (!entry) return null
+
+    if (entry.expiresAt !== null && Date.now() >= entry.expiresAt) {
+      this.entries.delete(key)
+      return null
+    }
+
+    return entry.value as T
+  }
+
+  async set(key: string, value: unknown, ttl?: number): Promise<void> {
+    const expiresAt = ttl != null ? Date.now() + ttl * 1000 : null
+
+    this.entries.set(key, { value, expiresAt })
+
+    if (this.entries.size > 10_000) this.cleanup()
+  }
+
+  async has(key: string): Promise<boolean> {
+    const entry = this.entries.get(key)
+    if (!entry) return false
+
+    if (entry.expiresAt !== null && Date.now() >= entry.expiresAt) {
+      this.entries.delete(key)
+      return false
+    }
+
+    return true
+  }
+
+  async forget(key: string): Promise<void> {
+    this.entries.delete(key)
+  }
+
+  async flush(): Promise<void> {
+    this.entries.clear()
+  }
+
+  private cleanup(): void {
+    const now = Date.now()
+    for (const [key, entry] of this.entries) {
+      if (entry.expiresAt !== null && now >= entry.expiresAt) {
+        this.entries.delete(key)
+      }
+    }
+  }
+}

package/src/config/configuration.ts

@@ -0,0 +1,105 @@
+import { readdirSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import EnvLoader from './loaders/env_loader'
+import TypescriptLoader from './loaders/typescript_loader'
+import type { ConfigData, ConfigurationLoader } from './types'
+
+export default class Configuration {
+  private data: ConfigData = {}
+  private configPath: string
+  private environment?: string
+  private loaders: ConfigurationLoader[] = [new EnvLoader(), new TypescriptLoader()]
+
+  constructor(configPath: string = './config', environment?: string) {
+    this.configPath = configPath
+    this.environment = environment
+  }
+
+  /**
+   * Scan the config directory and load every supported file.
+   * Each file is stored under a key derived from its name
+   * (e.g. `database.ts` → `"database"`).
+   */
+  async load(): Promise<void> {
+    let files: string[]
+    try {
+      files = readdirSync(this.configPath)
+    } catch {
+      return
+    }
+
+    for (const file of files) {
+      const filePath = join(this.configPath, file)
+      const loader = this.loaders.find(l => l.supports(filePath))
+      if (!loader) continue
+
+      const config = await loader.load(filePath, this.environment)
+      if (config === null) continue
+
+      let key = basename(file, '.' + file.split('.').pop())
+      // Handle dotfiles like .env where basename strips the entire name
+      if (!key) key = file.replace(/^\./, '')
+      this.data[key] = config
+    }
+  }
+
+  /**
+   * Retrieve a config value using dot notation.
+   *
+   * @example
+   * config.get('database.host')       // value of data.database.host
+   * config.get('database.port', 3306) // with fallback
+   */
+  get(key: string, defaultValue?: any): any {
+    const parts = key.split('.')
+    let current: any = this.data
+
+    for (const part of parts) {
+      if (current === undefined || current === null || typeof current !== 'object') {
+        return defaultValue
+      }
+      current = current[part]
+    }
+
+    return current !== undefined ? current : defaultValue
+  }
+
+  /** Check whether a key exists (even if its value is `undefined`). */
+  has(key: string): boolean {
+    const parts = key.split('.')
+    let current: any = this.data
+
+    for (const part of parts) {
+      if (current === undefined || current === null || typeof current !== 'object') {
+        return false
+      }
+      if (!(part in current)) {
+        return false
+      }
+      current = current[part]
+    }
+
+    return true
+  }
+
+  /** Set a config value using dot notation. */
+  set(key: string, value: any): void {
+    const parts = key.split('.')
+    const last = parts.pop()!
+    let current: any = this.data
+
+    for (const part of parts) {
+      if (current[part] === undefined || typeof current[part] !== 'object') {
+        current[part] = {}
+      }
+      current = current[part]
+    }
+
+    current[last] = value
+  }
+
+  /** Return all loaded config data. */
+  all(): ConfigData {
+    return this.data
+  }
+}

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export { default as Configuration } from './configuration'
+export type { ConfigData, ConfigurationLoader } from './types'

package/src/config/loaders/base_loader.ts

@@ -0,0 +1,69 @@
+import type { ConfigData, ConfigurationLoader } from '../types'
+
+/**
+ * Abstract base class for configuration loaders.
+ *
+ * Subclasses declare the file extensions they handle via {@link extensions} and
+ * implement {@link load} to parse a specific file format. Shared helpers for
+ * extension matching and environment-based config extraction are provided here.
+ */
+export abstract class BaseConfigurationLoader implements ConfigurationLoader {
+  /** File extensions this loader can handle (without the leading dot). */
+  protected extensions: string[] = []
+
+  /**
+   * Load and parse a configuration file.
+   *
+   * @param filePath - Absolute path to the configuration file.
+   * @param environment - Optional environment key (e.g. `"production"`) used
+   *   to select a nested section from the loaded config.
+   * @returns The parsed configuration data, or `null` if the file does not exist.
+   */
+  abstract load(filePath: string, environment?: string): Promise<ConfigData>
+
+  /**
+   * Check whether this loader supports the given file path based on its
+   * extension.
+   *
+   * @param filePath - Path to test.
+   * @returns `true` if the file's extension is in {@link extensions}.
+   */
+  supports(filePath: string): boolean {
+    const ext = this.getFileExtension(filePath)
+    return this.extensions.includes(ext)
+  }
+
+  /**
+   * Extract the lowercase file extension from a path.
+   *
+   * @param filePath - The file path to inspect.
+   * @returns The extension without a leading dot, or an empty string if none.
+   */
+  protected getFileExtension(filePath: string): string {
+    return filePath.split('.').pop()?.toLowerCase() || ''
+  }
+
+  /**
+   * Return the environment-specific subset of a configuration object.
+   *
+   * If `environment` is provided and the config object contains a matching
+   * top-level key, that nested value is returned. Otherwise the full config
+   * is returned unchanged.
+   *
+   * @param config - The full configuration object.
+   * @param environment - Optional environment key to look up.
+   * @returns The environment subset, or the original config if no match.
+   */
+  protected extractEnvironmentConfig(config: any, environment?: string): any {
+    if (!environment || typeof config !== 'object' || config === null) {
+      return config
+    }
+
+    // Check if config has environment-specific sections
+    if (config[environment]) {
+      return config[environment]
+    }
+
+    return config
+  }
+}

package/src/config/loaders/env_loader.ts

@@ -0,0 +1,112 @@
+import { BaseConfigurationLoader } from './base_loader'
+import { dirname, join } from 'node:path'
+
+/**
+ * Configuration loader for `.env` files.
+ *
+ * Loads the base `.env` file first, then merges values from an
+ * environment-specific file (e.g. `.env.test`, `.env.production`) on top,
+ * so environment-specific values override the base ones.
+ *
+ * @example
+ * // .env
+ * DB_HOST=localhost
+ * DB_PORT=5432
+ *
+ * // .env.production
+ * DB_HOST=db.example.com
+ *
+ * // Result when environment is "production":
+ * // { DB_HOST: "db.example.com", DB_PORT: "5432" }
+ */
+export default class EnvLoader extends BaseConfigurationLoader {
+  protected override extensions = ['env']
+
+  /**
+   * Load a `.env` file and optionally merge an environment-specific override
+   * file on top.
+   *
+   * Given a `filePath` of `/app/config/.env`, this will:
+   * 1. Parse `/app/config/.env` (if it exists)
+   * 2. Parse `/app/config/.env.{environment}` (if `environment` is provided and the file exists)
+   * 3. Return the merged result, with environment-specific values taking precedence.
+   *
+   * @param filePath - Absolute path to the base `.env` file.
+   * @param environment - Optional environment name (e.g. `"test"`, `"production"`).
+   * @returns The merged key-value pairs, or `null` if the base file does not exist.
+   * @throws If a file exists but cannot be read or parsed.
+   */
+  async load(filePath: string, environment?: string): Promise<any> {
+    const baseConfig = await this.parseEnvFile(filePath)
+
+    if (baseConfig === null) {
+      return null
+    }
+
+    if (!environment) {
+      return baseConfig
+    }
+
+    const dir = dirname(filePath)
+    const envFilePath = join(dir, `.env.${environment}`)
+    const envConfig = await this.parseEnvFile(envFilePath)
+
+    if (envConfig === null) {
+      return baseConfig
+    }
+
+    return { ...baseConfig, ...envConfig }
+  }
+
+  /**
+   * Parse a single `.env` file into a key-value object.
+   *
+   * Supports:
+   * - `KEY=value` pairs
+   * - Quoted values (single and double quotes are stripped)
+   * - Comments (lines starting with `#`)
+   * - Blank lines (ignored)
+   *
+   * @param filePath - Absolute path to the `.env` file.
+   * @returns The parsed key-value pairs, or `null` if the file does not exist.
+   */
+  private async parseEnvFile(filePath: string): Promise<Record<string, string> | null> {
+    const file = Bun.file(filePath)
+
+    if (!(await file.exists())) {
+      return null
+    }
+
+    const content = await file.text()
+    const result: Record<string, string> = {}
+
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim()
+
+      // Skip empty lines and comments
+      if (trimmed === '' || trimmed.startsWith('#')) {
+        continue
+      }
+
+      const separatorIndex = trimmed.indexOf('=')
+      if (separatorIndex === -1) {
+        continue
+      }
+
+      const key = trimmed.slice(0, separatorIndex).trim()
+      let value = trimmed.slice(separatorIndex + 1).trim()
+
+      // Strip surrounding quotes
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1)
+      }
+
+      result[key] = value
+    }
+
+    return result
+  }
+}

package/src/config/loaders/typescript_loader.ts

@@ -0,0 +1,56 @@
+import { BaseConfigurationLoader } from './base_loader'
+import { existsSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+
+/**
+ * Configuration loader for TypeScript and JavaScript files.
+ *
+ * Dynamically imports `.ts` and `.js` configuration files using Bun's native
+ * TypeScript support, and optionally extracts an environment-specific section
+ * from the exported config object.
+ *
+ * Config files should default-export a configuration object. When an
+ * `environment` is provided, the loader looks for a matching top-level key
+ * and returns that subset instead of the full object.
+ *
+ * @example
+ * // config/database.ts
+ * export default {
+ *   development: { host: 'localhost', port: 5432 },
+ *   production:  { host: 'db.example.com', port: 5432 },
+ * }
+ */
+export default class TypescriptLoader extends BaseConfigurationLoader {
+  protected override extensions = ['ts', 'js']
+
+  /**
+   * Load and evaluate a TypeScript or JavaScript configuration file.
+   *
+   * @param filePath - Absolute path to the config file.
+   * @param environment - Optional environment key (e.g. `"production"`) used
+   *   to extract a nested section from the config object.
+   * @returns The resolved configuration object, the environment-specific
+   *   subset if found, or `null` if the file does not exist.
+   * @throws If the file exists but cannot be imported or evaluated.
+   */
+  async load(filePath: string, environment?: string): Promise<any> {
+    if (!existsSync(filePath)) {
+      return null
+    }
+
+    try {
+      // Convert to file URL for dynamic import
+      const fileUrl = pathToFileURL(filePath).href
+      const module = await import(fileUrl + '?t=' + Date.now())
+
+      let config = module.default || module
+
+      // Extract environment-specific config
+      config = this.extractEnvironmentConfig(config, environment)
+
+      return config
+    } catch (error) {
+      throw new Error(`Failed to load TypeScript/JavaScript config from ${filePath}: ${error}`)
+    }
+  }
+}

package/src/config/types.ts

@@ -0,0 +1,8 @@
+export interface ConfigData {
+  [key: string]: any
+}
+
+export interface ConfigurationLoader {
+  supports(filePath: string): boolean
+  load(filePath: string, environment?: string): Promise<ConfigData>
+}