@stravigor/core 0.1.0

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

@@ -0,0 +1,12 @@
+import BaseModel from '../orm/base_model.ts'
+
+/** Extract a user ID from a BaseModel instance or a raw string/number. */
+export function extractUserId(user: unknown): string {
+  if (typeof user === 'string') return user
+  if (typeof user === 'number') return String(user)
+  if (user instanceof BaseModel) {
+    const ctor = user.constructor as typeof BaseModel
+    return String((user as unknown as Record<string, unknown>)[ctor.primaryKeyProperty])
+  }
+  throw new Error('Pass a BaseModel instance or a string/number user ID.')
+}

package/src/helpers/index.ts

@@ -0,0 +1,4 @@
+export { toSnakeCase, toCamelCase, toPascalCase } from './strings.ts'
+export { env } from './env.ts'
+export { randomHex } from './crypto.ts'
+export { extractUserId } from './identity.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/http/context.ts

@@ -0,0 +1,215 @@
+import { parseCookies } from './cookie.ts'
+import type ViewEngine from '../view/engine.ts'
+import { ConfigurationError } from '../exceptions/errors.ts'
+
+/**
+ * HTTP request context — the primary object handlers interact with.
+ *
+ * Wraps Bun's native Request and adds route params, body parsing,
+ * response helpers, and a type-safe state bag for middleware.
+ */
+export default class Context {
+  private static _viewEngine: ViewEngine | null = null
+
+  static setViewEngine(engine: ViewEngine): void {
+    Context._viewEngine = engine
+  }
+
+  readonly url: URL
+  readonly method: string
+  readonly path: string
+  readonly headers: Headers
+
+  private _state = new Map<string, unknown>()
+  private _subdomain?: string
+  private _query?: URLSearchParams
+  private _cookies?: Map<string, string>
+  private _body?: unknown
+  private _bodyParsed = false
+
+  constructor(
+    readonly request: Request,
+    readonly params: Record<string, string> = {},
+    private domain: string = 'localhost'
+  ) {
+    this.url = new URL(request.url)
+    this.method = request.method
+    this.path = this.url.pathname
+    this.headers = request.headers
+  }
+
+  // ---------------------------------------------------------------------------
+  // Request helpers
+  // ---------------------------------------------------------------------------
+
+  /** Parsed query string parameters. */
+  get query(): URLSearchParams {
+    if (!this._query) this._query = this.url.searchParams
+    return this._query
+  }
+
+  /** Subdomain extracted from the Host header relative to the configured domain. */
+  get subdomain(): string {
+    if (this._subdomain !== undefined) return this._subdomain
+
+    const host = this.headers.get('host') ?? ''
+    const hostname = host.split(':')[0] ?? ''
+
+    if (hostname.endsWith(this.domain) && hostname.length > this.domain.length) {
+      this._subdomain = hostname.slice(0, -(this.domain.length + 1))
+    } else {
+      this._subdomain = ''
+    }
+
+    return this._subdomain
+  }
+
+  /** Shorthand for reading a single request header. */
+  header(name: string): string | null {
+    return this.headers.get(name)
+  }
+
+  /** Read a query string parameter, with optional typed default. */
+  qs(name: string): string | null
+  qs(name: string, defaultValue: number): number
+  qs(name: string, defaultValue: string): string
+  qs(name: string, defaultValue?: string | number): string | number | null {
+    const value = this.query.get(name)
+    if (value === null || value === '') return defaultValue ?? null
+    if (typeof defaultValue === 'number') {
+      const parsed = Number(value)
+      return Number.isNaN(parsed) ? defaultValue : parsed
+    }
+    return value
+  }
+
+  /** Read a cookie value by name from the Cookie header. */
+  cookie(name: string): string | null {
+    if (!this._cookies) {
+      this._cookies = parseCookies(this.headers.get('cookie') ?? '')
+    }
+    return this._cookies.get(name) ?? null
+  }
+
+  /** Extract named string fields from a form body. With no args, returns all non-file fields. */
+  async inputs<K extends string>(...keys: K[]): Promise<Record<K, string>> {
+    const form = await this.body<FormData>()
+    const result = {} as Record<K, string>
+    if (keys.length === 0) {
+      form.forEach((value, key) => {
+        if (typeof value === 'string') (result as Record<string, string>)[key] = value
+      })
+    } else {
+      for (const key of keys) {
+        const value = form.get(key)
+        result[key] = typeof value === 'string' ? value : ''
+      }
+    }
+    return result
+  }
+
+  /** Extract named file fields from a form body. With no args, returns all file fields. */
+  async files<K extends string>(...keys: K[]): Promise<Record<K, File | null>> {
+    const form = await this.body<FormData>()
+    const result = {} as Record<K, File | null>
+    if (keys.length === 0) {
+      form.forEach((value, key) => {
+        if (value instanceof File) (result as Record<string, File>)[key] = value
+      })
+    } else {
+      for (const key of keys) {
+        const value = form.get(key)
+        result[key] = value instanceof File ? value : null
+      }
+    }
+    return result
+  }
+
+  /**
+   * Parse the request body. Automatically detects JSON, form-data, and text.
+   * The result is cached — safe to call multiple times.
+   */
+  async body<T = unknown>(): Promise<T> {
+    if (!this._bodyParsed) {
+      const contentType = this.header('content-type') ?? ''
+
+      if (contentType.includes('application/json')) {
+        this._body = await this.request.json()
+      } else if (
+        contentType.includes('multipart/form-data') ||
+        contentType.includes('application/x-www-form-urlencoded')
+      ) {
+        this._body = await this.request.formData()
+      } else {
+        this._body = await this.request.text()
+      }
+
+      this._bodyParsed = true
+    }
+
+    return this._body as T
+  }
+
+  // ---------------------------------------------------------------------------
+  // Response helpers
+  // ---------------------------------------------------------------------------
+
+  json(data: unknown, status = 200): Response {
+    return new Response(JSON.stringify(data), {
+      status,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+
+  text(content: string, status = 200): Response {
+    return new Response(content, {
+      status,
+      headers: { 'Content-Type': 'text/plain' },
+    })
+  }
+
+  html(content: string, status = 200): Response {
+    return new Response(content, {
+      status,
+      headers: { 'Content-Type': 'text/html' },
+    })
+  }
+
+  redirect(url: string, status = 302): Response {
+    return new Response(null, {
+      status,
+      headers: { Location: url },
+    })
+  }
+
+  empty(status = 204): Response {
+    return new Response(null, { status })
+  }
+
+  async view(template: string, data?: Record<string, unknown>, status = 200): Promise<Response> {
+    if (!Context._viewEngine) {
+      throw new ConfigurationError('ViewEngine not configured. Register it in the container.')
+    }
+    const html = await Context._viewEngine.render(template, data)
+    return this.html(html, status)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Middleware state
+  // ---------------------------------------------------------------------------
+
+  /** Store a value for downstream middleware / handlers. */
+  set<T>(key: string, value: T): void {
+    this._state.set(key, value)
+  }
+
+  /** Retrieve a value set by upstream middleware. */
+  get<T>(key: string): T
+  get<T1, T2>(k1: string, k2: string): [T1, T2]
+  get<T1, T2, T3>(k1: string, k2: string, k3: string): [T1, T2, T3]
+  get<T1, T2, T3, T4>(k1: string, k2: string, k3: string, k4: string): [T1, T2, T3, T4]
+  get(...keys: string[]): unknown {
+    if (keys.length === 1) return this._state.get(keys[0]!)
+    return keys.map(k => this._state.get(k))
+  }
+}

package/src/http/cookie.ts

@@ -0,0 +1,59 @@
+/** Options for serializing a Set-Cookie header. */
+export interface CookieOptions {
+  httpOnly?: boolean
+  secure?: boolean
+  sameSite?: 'strict' | 'lax' | 'none'
+  maxAge?: number // seconds
+  path?: string
+  domain?: string
+}
+
+/** Serialize a cookie name/value pair into a Set-Cookie header string. */
+export function serializeCookie(name: string, value: string, options: CookieOptions = {}): string {
+  let cookie = `${name}=${encodeURIComponent(value)}`
+
+  if (options.httpOnly) cookie += '; HttpOnly'
+  if (options.secure) cookie += '; Secure'
+  if (options.sameSite) cookie += `; SameSite=${options.sameSite}`
+  if (options.maxAge !== undefined) cookie += `; Max-Age=${options.maxAge}`
+  cookie += `; Path=${options.path ?? '/'}`
+  if (options.domain) cookie += `; Domain=${options.domain}`
+
+  return cookie
+}
+
+/** Parse a Cookie header string into a map of name → value. */
+export function parseCookies(header: string): Map<string, string> {
+  const cookies = new Map<string, string>()
+
+  for (const pair of header.split(';')) {
+    const eq = pair.indexOf('=')
+    if (eq === -1) continue
+    const key = pair.slice(0, eq).trim()
+    const value = decodeURIComponent(pair.slice(eq + 1).trim())
+    cookies.set(key, value)
+  }
+
+  return cookies
+}
+
+/** Return a new Response with a Set-Cookie header appended. */
+export function withCookie(
+  response: Response,
+  name: string,
+  value: string,
+  options?: CookieOptions
+): Response {
+  const headers = new Headers(response.headers)
+  headers.append('Set-Cookie', serializeCookie(name, value, options))
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}
+
+/** Return a new Response with a cookie-clearing Set-Cookie header (Max-Age=0). */
+export function clearCookie(response: Response, name: string, options?: CookieOptions): Response {
+  return withCookie(response, name, '', { ...options, maxAge: 0 })
+}

package/src/http/cors.ts

@@ -0,0 +1,163 @@
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CorsOptions {
+  /**
+   * Allowed origins. Determines Access-Control-Allow-Origin.
+   *
+   * - `'*'` — allow all origins (incompatible with credentials)
+   * - `string` — a single exact origin
+   * - `string[]` — an allow-list of exact origins
+   * - `RegExp` — pattern tested against the request Origin header
+   * - `(origin: string) => boolean` — callback for custom logic
+   *
+   * @default '*'
+   */
+  origin?: string | string[] | RegExp | ((origin: string) => boolean)
+
+  /**
+   * Allowed HTTP methods for preflight responses.
+   * @default ['GET','HEAD','PUT','PATCH','POST','DELETE']
+   */
+  methods?: string[]
+
+  /**
+   * Allowed request headers for preflight responses.
+   * When unset, mirrors the Access-Control-Request-Headers from the preflight.
+   */
+  allowedHeaders?: string[]
+
+  /** Headers exposed to the browser via Access-Control-Expose-Headers. */
+  exposedHeaders?: string[]
+
+  /**
+   * Include Access-Control-Allow-Credentials: true.
+   * When true, origin cannot be literal `'*'` — the actual request origin is reflected.
+   * @default false
+   */
+  credentials?: boolean
+
+  /**
+   * Preflight cache duration in seconds (Access-Control-Max-Age).
+   * @default 86400
+   */
+  maxAge?: number
+}
+
+/** Resolved config with defaults applied. */
+export interface ResolvedCorsConfig {
+  origin: string | string[] | RegExp | ((origin: string) => boolean)
+  methods: string[]
+  allowedHeaders?: string[]
+  exposedHeaders?: string[]
+  credentials: boolean
+  maxAge: number
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULTS: ResolvedCorsConfig = {
+  origin: '*',
+  methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'],
+  credentials: false,
+  maxAge: 86400,
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Merge user options with defaults. */
+export function resolveCorsConfig(options?: CorsOptions): ResolvedCorsConfig {
+  return { ...DEFAULTS, ...options }
+}
+
+/**
+ * Determine the Access-Control-Allow-Origin value for a request origin.
+ * Returns `null` when the origin is not allowed.
+ */
+export function resolveOrigin(
+  config: ResolvedCorsConfig,
+  requestOrigin: string | null
+): string | null {
+  const { origin, credentials } = config
+
+  if (!requestOrigin) return credentials ? null : '*'
+
+  if (origin === '*') return credentials ? requestOrigin : '*'
+  if (typeof origin === 'string') return origin === requestOrigin ? origin : null
+  if (Array.isArray(origin)) return origin.includes(requestOrigin) ? requestOrigin : null
+  if (origin instanceof RegExp) return origin.test(requestOrigin) ? requestOrigin : null
+  if (typeof origin === 'function') return origin(requestOrigin) ? requestOrigin : null
+
+  return null
+}
+
+/** Build a 204 preflight response with CORS headers. */
+export function preflightResponse(
+  config: ResolvedCorsConfig,
+  requestOrigin: string | null,
+  requestHeaders: string | null
+): Response {
+  const allowedOrigin = resolveOrigin(config, requestOrigin)
+
+  if (!allowedOrigin) return new Response(null, { status: 204 })
+
+  const headers = new Headers()
+  headers.set('Access-Control-Allow-Origin', allowedOrigin)
+  headers.set('Access-Control-Allow-Methods', config.methods.join(', '))
+  headers.set('Access-Control-Max-Age', String(config.maxAge))
+
+  if (config.credentials) {
+    headers.set('Access-Control-Allow-Credentials', 'true')
+  }
+
+  if (config.allowedHeaders) {
+    headers.set('Access-Control-Allow-Headers', config.allowedHeaders.join(', '))
+  } else if (requestHeaders) {
+    headers.set('Access-Control-Allow-Headers', requestHeaders)
+  }
+
+  if (allowedOrigin !== '*') {
+    headers.set('Vary', 'Origin')
+  }
+
+  return new Response(null, { status: 204, headers })
+}
+
+/** Return a new Response with CORS headers appended. */
+export function withCorsHeaders(
+  response: Response,
+  config: ResolvedCorsConfig,
+  requestOrigin: string | null
+): Response {
+  const allowedOrigin = resolveOrigin(config, requestOrigin)
+  if (!allowedOrigin) return response
+
+  const headers = new Headers(response.headers)
+  headers.set('Access-Control-Allow-Origin', allowedOrigin)
+
+  if (config.credentials) {
+    headers.set('Access-Control-Allow-Credentials', 'true')
+  }
+
+  if (config.exposedHeaders?.length) {
+    headers.set('Access-Control-Expose-Headers', config.exposedHeaders.join(', '))
+  }
+
+  if (allowedOrigin !== '*') {
+    const existing = headers.get('Vary')
+    if (!existing?.includes('Origin')) {
+      headers.set('Vary', existing ? `${existing}, Origin` : 'Origin')
+    }
+  }
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}

package/src/http/index.ts

@@ -0,0 +1,16 @@
+import { app } from '../core/application.ts'
+import Router from './router.ts'
+
+export { default as Context } from './context.ts'
+export { default as Router } from './router.ts'
+export { default as Server } from './server.ts'
+export { compose } from './middleware.ts'
+export { serializeCookie, parseCookies, withCookie, clearCookie } from './cookie.ts'
+export { rateLimit, MemoryStore } from './rate_limit.ts'
+export type { Handler, Middleware, Next } from './middleware.ts'
+export type { GroupOptions, WebSocketHandlers, WebSocketData } from './router.ts'
+export type { CookieOptions } from './cookie.ts'
+export type { CorsOptions } from './cors.ts'
+export type { RateLimitOptions, RateLimitStore, RateLimitInfo } from './rate_limit.ts'
+
+export const router = app.resolve(Router)

package/src/http/middleware.ts

@@ -0,0 +1,39 @@
+import type Context from './context.ts'
+
+/** A route handler — receives a Context and returns a Response. */
+export type Handler = (ctx: Context) => Response | Promise<Response>
+
+/** Invokes the next middleware (or the final handler) in the pipeline. */
+export type Next = () => Promise<Response>
+
+/** A middleware function — wraps a handler with before/after logic. */
+export type Middleware = (ctx: Context, next: Next) => Response | Promise<Response>
+
+/**
+ * Compose an array of middleware and a final handler into a single handler.
+ *
+ * Implements the onion model: each middleware wraps the next, and can
+ * inspect or modify the response on the way back.
+ *
+ * @example
+ * const handler = compose([logger, auth], finalHandler)
+ * const response = await handler(ctx)
+ */
+export function compose(middleware: Middleware[], handler: Handler): Handler {
+  return (ctx: Context) => {
+    let index = -1
+
+    function dispatch(i: number): Promise<Response> {
+      if (i <= index) throw new Error('next() called multiple times')
+      index = i
+
+      if (i === middleware.length) {
+        return Promise.resolve(handler(ctx))
+      }
+
+      return Promise.resolve(middleware[i]!(ctx, () => dispatch(i + 1)))
+    }
+
+    return dispatch(0)
+  }
+}