@stravigor/core 0.1.0

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/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>
+}

package/src/core/application.ts

@@ -0,0 +1,4 @@
+import Container from './container.ts'
+
+/** Global application container singleton. */
+export const app = new Container()

package/src/core/container.ts

@@ -0,0 +1,117 @@
+import 'reflect-metadata'
+import { INJECTABLE } from './inject.ts'
+
+/** Constructor type for injectable classes. */
+type Constructor<T = any> = new (...args: any[]) => T
+
+/** A factory function that receives the container and returns a service instance. */
+type Factory<T = any> = (container: Container) => T
+
+/**
+ * A lightweight dependency injection container.
+ *
+ * Services are registered as factory functions or `@inject`-decorated classes
+ * and resolved by string name or class constructor.
+ *
+ * @example
+ * const app = new Container()
+ *   .singleton(Database)
+ *   .singleton(UserService)              // @inject decorated
+ *   .singleton('logger', () => new Logger())
+ *
+ * const svc = app.resolve(UserService)   // Database auto-injected
+ */
+export default class Container {
+  private factories = new Map<any, { factory: Factory; singleton: boolean }>()
+  private instances = new Map<any, any>()
+
+  /** Create a factory from a class constructor, resolving `design:paramtypes` metadata. */
+  private classToFactory<T>(Cls: Constructor<T>): Factory<T> {
+    const paramTypes: Constructor[] = Reflect.getMetadata('design:paramtypes', Cls) ?? []
+    return (c: Container) => new Cls(...paramTypes.map(dep => c.resolve(dep)))
+  }
+
+  /** Wrap an `@inject`-decorated class in a factory, or return a plain factory as-is. */
+  private toFactory<T>(factoryOrClass: Factory<T> | Constructor<T>): Factory<T> {
+    if (INJECTABLE in factoryOrClass) {
+      return this.classToFactory(factoryOrClass as Constructor<T>)
+    }
+    return factoryOrClass as Factory<T>
+  }
+
+  /** Register an `@inject` class that creates a new instance on every {@link resolve} call. */
+  register<T>(ctor: Constructor<T>): this
+  /** Register a factory under a class constructor key. Creates a new instance on every {@link resolve} call. */
+  register<T>(ctor: Constructor<T>, factory: Factory<T>): this
+  /** Register a factory or `@inject` class under a string name. Creates a new instance on every {@link resolve} call. */
+  register<T>(name: string, factory: Factory<T> | Constructor<T>): this
+  register<T>(nameOrCtor: string | Constructor<T>, factory?: Factory<T> | Constructor<T>): this {
+    if (typeof nameOrCtor === 'function') {
+      const resolved = factory
+        ? this.toFactory(factory)
+        : this.classToFactory(nameOrCtor)
+      this.factories.set(nameOrCtor, { factory: resolved, singleton: false })
+    } else {
+      this.factories.set(nameOrCtor, { factory: this.toFactory(factory!), singleton: false })
+    }
+    return this
+  }
+
+  /** Register an `@inject` class as a singleton by its constructor. */
+  singleton<T>(ctor: Constructor<T>): this
+  /** Register a factory under a class constructor key (resolved by constructor). */
+  singleton<T>(ctor: Constructor<T>, factory: Factory<T>): this
+  /** Register a factory or `@inject` class as a singleton under a string name. */
+  singleton<T>(name: string, factory: Factory<T> | Constructor<T>): this
+  singleton<T>(nameOrCtor: string | Constructor<T>, factory?: Factory<T> | Constructor<T>): this {
+    if (typeof nameOrCtor === 'function') {
+      const resolved = factory
+        ? this.toFactory(factory)
+        : this.classToFactory(nameOrCtor)
+      this.factories.set(nameOrCtor, { factory: resolved, singleton: true })
+    } else {
+      this.factories.set(nameOrCtor, { factory: this.toFactory(factory!), singleton: true })
+    }
+    return this
+  }
+
+  /** Resolve a service by its class constructor. */
+  resolve<T>(ctor: Constructor<T>): T
+  /** Resolve a service by its string name. */
+  resolve<T>(name: string): T
+  resolve<T>(key: string | Constructor<T>): T {
+    const entry = this.factories.get(key)
+    if (!entry) {
+      const label = typeof key === 'string' ? `"${key}"` : key.name
+      throw new Error(`Service ${label} is not registered`)
+    }
+
+    if (entry.singleton) {
+      if (!this.instances.has(key)) {
+        this.instances.set(key, entry.factory(this))
+      }
+      return this.instances.get(key)
+    }
+
+    return entry.factory(this)
+  }
+
+  /** Check whether a service has been registered under the given name or constructor. */
+  has(key: string | Constructor): boolean {
+    return this.factories.has(key)
+  }
+
+  /**
+   * Instantiate a class with automatic dependency injection.
+   *
+   * Unlike {@link resolve}, this does not require prior registration.
+   * Constructor dependencies are resolved recursively: registered services
+   * are pulled from the container, unregistered `@inject` classes are
+   * instantiated via `make()` as well.
+   */
+  make<T>(ctor: Constructor<T>): T {
+    const paramTypes: Constructor[] = Reflect.getMetadata('design:paramtypes', ctor) ?? []
+    const deps = paramTypes.map(dep => (this.has(dep) ? this.resolve(dep) : this.make(dep)))
+    return new ctor(...deps)
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,3 @@
+export { app } from './application.ts'
+export { default as Container } from './container.ts'
+export { inject, INJECTABLE } from './inject.ts'

package/src/core/inject.ts

@@ -0,0 +1,39 @@
+import 'reflect-metadata'
+
+/** Symbol used to mark a class as injectable. */
+export const INJECTABLE = Symbol('inject:injectable')
+
+/**
+ * Class decorator that marks a class as injectable.
+ *
+ * With `emitDecoratorMetadata` enabled, TypeScript automatically emits
+ * constructor parameter type metadata (`design:paramtypes`). The container
+ * reads this metadata to auto-resolve dependencies by class reference.
+ *
+ * Works as both `@inject` and `@inject()`.
+ *
+ * @example
+ * @inject
+ * class UserService {
+ *   constructor(protected db: Database, protected logger: Logger) {}
+ * }
+ *
+ * container.singleton(Database)
+ * container.singleton(Logger)
+ * container.singleton(UserService)
+ * container.resolve(UserService) // db and logger auto-injected by type
+ */
+export function inject<T extends Function>(target: T): void
+export function inject(): <T extends Function>(target: T) => void
+export function inject(target?: any) {
+  const mark = (cls: any) => {
+    Object.defineProperty(cls, INJECTABLE, { value: true, enumerable: false })
+  }
+  if (typeof target === 'function') {
+    mark(target)
+    return
+  }
+  return (cls: any) => {
+    mark(cls)
+  }
+}

package/src/database/database.ts

@@ -0,0 +1,54 @@
+import { SQL } from 'bun'
+import Configuration from '../config/configuration.ts'
+import { inject } from '../core/inject.ts'
+import { ConfigurationError } from '../exceptions/errors.ts'
+
+/**
+ * Database connection wrapper backed by {@link SQL Bun.sql}.
+ *
+ * Reads connection credentials from the `database.*` configuration keys
+ * (loaded from `config/database.ts` / `.env`).
+ *
+ * Register as a singleton in the DI container so a single connection pool
+ * is shared across the application.
+ *
+ * @example
+ * container.singleton(Configuration)
+ * container.singleton(Database)
+ * const db = container.resolve(Database)
+ * const rows = await db.sql`SELECT 1 AS result`
+ */
+@inject
+export default class Database {
+  private static _connection: SQL | null = null
+  private connection: SQL
+
+  constructor(protected config: Configuration) {
+    this.connection = new SQL({
+      hostname: config.get('database.host', '127.0.0.1'),
+      port: config.get('database.port', 5432),
+      username: config.get('database.username', 'postgres'),
+      password: config.get('database.password', ''),
+      database: config.get('database.database', 'strav'),
+    })
+    Database._connection = this.connection
+  }
+
+  /** The underlying Bun SQL tagged-template client. */
+  get sql(): SQL {
+    return this.connection
+  }
+
+  /** The global SQL connection, available after DI bootstrap. */
+  static get raw(): SQL {
+    if (!Database._connection) {
+      throw new ConfigurationError('Database not configured. Resolve Database through the container first.')
+    }
+    return Database._connection
+  }
+
+  /** Close the connection pool. */
+  async close(): Promise<void> {
+    await this.connection.close()
+  }
+}

package/src/database/index.ts

@@ -0,0 +1,30 @@
+import type { SQL } from 'bun'
+import Database from './database.ts'
+
+export { default as Database } from './database.ts'
+export { default as DatabaseIntrospector } from './introspector.ts'
+export { default as QueryBuilder, query } from './query_builder.ts'
+export type { PaginationResult, PaginationMeta } from './query_builder.ts'
+export * from './migration/index.ts'
+
+/**
+ * Pre-configured SQL tagged-template client.
+ *
+ * A transparent proxy to the Database singleton's underlying Bun SQL connection.
+ * Available after the Database is resolved through the DI container.
+ *
+ * @example
+ * import { sql } from '@stravigor/core/database'
+ * const rows = await sql`SELECT * FROM "user" WHERE "id" = ${id}`
+ * await sql.begin(async (tx) => { ... })
+ */
+export const sql: SQL = new Proxy((() => {}) as unknown as SQL, {
+  apply(_target, _thisArg, args) {
+    return (Database.raw as any)(...args)
+  },
+  get(_target, prop) {
+    const real = Database.raw
+    const val = (real as any)[prop]
+    return typeof val === 'function' ? val.bind(real) : val
+  },
+})