@strav/kernel 0.1.0

package/src/logger/logger.ts

@@ -0,0 +1,113 @@
+import pino from 'pino'
+import Configuration from '../config/configuration.ts'
+import { inject } from '../core/inject.ts'
+import Emitter from '../events/emitter.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)
+    this.emitLog('trace', msg, context)
+  }
+
+  /** Log at `debug` level. */
+  debug(msg: string, context?: Record<string, unknown>): void {
+    context ? this.pino.debug(context, msg) : this.pino.debug(msg)
+    this.emitLog('debug', msg, context)
+  }
+
+  /** Log at `info` level. */
+  info(msg: string, context?: Record<string, unknown>): void {
+    context ? this.pino.info(context, msg) : this.pino.info(msg)
+    this.emitLog('info', msg, context)
+  }
+
+  /** Log at `warn` level. */
+  warn(msg: string, context?: Record<string, unknown>): void {
+    context ? this.pino.warn(context, msg) : this.pino.warn(msg)
+    this.emitLog('warn', msg, context)
+  }
+
+  /** Log at `error` level. */
+  error(msg: string, context?: Record<string, unknown>): void {
+    context ? this.pino.error(context, msg) : this.pino.error(msg)
+    this.emitLog('error', msg, context)
+  }
+
+  /** Log at `fatal` level (most severe). */
+  fatal(msg: string, context?: Record<string, unknown>): void {
+    context ? this.pino.fatal(context, msg) : this.pino.fatal(msg)
+    this.emitLog('fatal', msg, context)
+  }
+
+  /** Emit a log event for devtools/observability consumers. Fire-and-forget. */
+  private emitLog(level: string, msg: string, context?: Record<string, unknown>): void {
+    if (Emitter.listenerCount('log:entry') === 0) return
+    Emitter.emit('log:entry', { level, msg, context }).catch(() => {})
+  }
+
+  /**
+   * 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/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'
+  }
+}

package/src/providers/cache_provider.ts

@@ -0,0 +1,16 @@
+import ServiceProvider from '../core/service_provider.ts'
+import type Application from '../core/application.ts'
+import CacheManager from '../cache/cache_manager.ts'
+
+export default class CacheProvider extends ServiceProvider {
+  readonly name = 'cache'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(CacheManager)
+  }
+
+  override boot(app: Application): void {
+    app.resolve(CacheManager)
+  }
+}

package/src/providers/config_provider.ts

@@ -0,0 +1,26 @@
+import ServiceProvider from '../core/service_provider.ts'
+import type Application from '../core/application.ts'
+import Configuration from '../config/configuration.ts'
+
+export interface ConfigProviderOptions {
+  /** Path to the config directory. Default: `'./config'` */
+  directory?: string
+}
+
+export default class ConfigProvider extends ServiceProvider {
+  readonly name = 'config'
+
+  constructor(private options?: ConfigProviderOptions) {
+    super()
+  }
+
+  override register(app: Application): void {
+    const dir = this.options?.directory ?? './config'
+    app.singleton(Configuration, () => new Configuration(dir))
+  }
+
+  override async boot(app: Application): Promise<void> {
+    const config = app.resolve(Configuration)
+    await config.load()
+  }
+}

package/src/providers/encryption_provider.ts

@@ -0,0 +1,16 @@
+import ServiceProvider from '../core/service_provider.ts'
+import type Application from '../core/application.ts'
+import EncryptionManager from '../encryption/encryption_manager.ts'
+
+export default class EncryptionProvider extends ServiceProvider {
+  readonly name = 'encryption'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(EncryptionManager)
+  }
+
+  override boot(app: Application): void {
+    app.resolve(EncryptionManager)
+  }
+}

package/src/providers/i18n_provider.ts

@@ -0,0 +1,17 @@
+import ServiceProvider from '../core/service_provider.ts'
+import type Application from '../core/application.ts'
+import I18nManager from '../i18n/i18n_manager.ts'
+
+export default class I18nProvider extends ServiceProvider {
+  readonly name = 'i18n'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(I18nManager)
+  }
+
+  override async boot(app: Application): Promise<void> {
+    app.resolve(I18nManager)
+    await I18nManager.load()
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,8 @@
+export { default as ConfigProvider } from './config_provider.ts'
+export { default as EncryptionProvider } from './encryption_provider.ts'
+export { default as StorageProvider } from './storage_provider.ts'
+export { default as CacheProvider } from './cache_provider.ts'
+export { default as I18nProvider } from './i18n_provider.ts'
+export { default as LoggerProvider } from './logger_provider.ts'
+
+export type { ConfigProviderOptions } from './config_provider.ts'

package/src/providers/logger_provider.ts

@@ -0,0 +1,16 @@
+import ServiceProvider from '../core/service_provider.ts'
+import type Application from '../core/application.ts'
+import Logger from '../logger/logger.ts'
+
+export default class LoggerProvider extends ServiceProvider {
+  readonly name = 'logger'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(Logger)
+  }
+
+  override boot(app: Application): void {
+    app.resolve(Logger)
+  }
+}

package/src/providers/storage_provider.ts

@@ -0,0 +1,16 @@
+import ServiceProvider from '../core/service_provider.ts'
+import type Application from '../core/application.ts'
+import StorageManager from '../storage/storage_manager.ts'
+
+export default class StorageProvider extends ServiceProvider {
+  readonly name = 'storage'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(StorageManager)
+  }
+
+  override boot(app: Application): void {
+    app.resolve(StorageManager)
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,32 @@
+export { default as Storage } from './storage.ts'
+export { Upload, FileTooLargeError, InvalidFileTypeError } from './upload.ts'
+export { default as StorageManager } from './storage_manager.ts'
+export { default as LocalDriver } from './local_driver.ts'
+export { default as S3Driver } from './s3_driver.ts'
+export { default as OstraDriver } from './ostra_driver.ts'
+export { default as OstraClient, OstraBucket, OstraMultipart, OstraError } from './ostra_client.ts'
+export type {
+  StorageDriver,
+  StorageConfig,
+  FileStats,
+  LocalDriverConfig,
+  S3DriverConfig,
+  OstraDriverConfig,
+} from './types.ts'
+export type { UploadResult } from './upload.ts'
+export type {
+  OstraClientConfig,
+  BucketInfo,
+  BucketStats,
+  ObjectMeta,
+  ObjectHeaders,
+  ListResult,
+  VersionInfo,
+  VersionListResult,
+  BatchDeleteResult,
+  SignedUrlResult,
+  MultipartInfo,
+  PartInfo,
+  TokenInfo,
+  TokenRecord,
+} from './ostra_client.ts'

package/src/storage/local_driver.ts

@@ -0,0 +1,46 @@
+import { join, extname, resolve } from 'node:path'
+import { unlink } from 'node:fs/promises'
+import { randomHex } from '../helpers/crypto.ts'
+import type { StorageDriver, LocalDriverConfig } from './types.ts'
+
+export default class LocalDriver implements StorageDriver {
+  private root: string
+  private baseUrl: string
+
+  constructor(config: LocalDriverConfig) {
+    this.root = resolve(config.root)
+    this.baseUrl = config.baseUrl
+  }
+
+  async put(directory: string, file: File, name?: string): Promise<string> {
+    const ext = extname(file.name)
+    const filename = name ?? `${randomHex(8)}${ext}`
+    const relativePath = join(directory, filename)
+    const fullPath = join(this.root, relativePath)
+
+    await Bun.write(fullPath, file)
+
+    return relativePath
+  }
+
+  async get(path: string): Promise<Blob | null> {
+    const file = Bun.file(join(this.root, path))
+    if (!(await file.exists())) return null
+    return file
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return Bun.file(join(this.root, path)).exists()
+  }
+
+  async delete(path: string): Promise<void> {
+    const fullPath = join(this.root, path)
+    if (await Bun.file(fullPath).exists()) {
+      await unlink(fullPath)
+    }
+  }
+
+  url(path: string): string {
+    return `${this.baseUrl}/${path}`
+  }
+}