@stravigor/core 0.1.0

package/src/broadcast/index.ts

@@ -0,0 +1,58 @@
+export { default, default as BroadcastManager } from './broadcast_manager.ts'
+export type {
+  AuthorizeCallback,
+  MessageHandler,
+  ChannelConfig,
+  BootOptions,
+  PendingBroadcast,
+} from './broadcast_manager.ts'
+export { Broadcast, Subscription } from './client.ts'
+export type { BroadcastOptions } from './client.ts'
+
+import BroadcastManager from './broadcast_manager.ts'
+import type { AuthorizeCallback, ChannelConfig, BootOptions } from './broadcast_manager.ts'
+import type Router from '../http/router.ts'
+
+/**
+ * Broadcast helper — convenience object that delegates to `BroadcastManager`.
+ *
+ * @example
+ * import { broadcast } from '@stravigor/core/broadcast'
+ *
+ * // Bootstrap
+ * broadcast.boot(router, { middleware: [session()] })
+ *
+ * // Define channels
+ * broadcast.channel('notifications')
+ * broadcast.channel('chats/:id', async (ctx, { id }) => !!ctx.get('user'))
+ *
+ * // Broadcast from anywhere
+ * broadcast.to('notifications').send('alert', { text: 'Hello' })
+ * broadcast.to(`chats/${chatId}`).except(senderId).send('message', data)
+ */
+export const broadcast = {
+  /** Register the broadcast WebSocket endpoint on the router. */
+  boot(router: Router, options?: BootOptions): void {
+    BroadcastManager.boot(router, options)
+  },
+
+  /** Register a channel with optional authorization and message handlers. */
+  channel(pattern: string, config?: AuthorizeCallback | ChannelConfig): void {
+    BroadcastManager.channel(pattern, config)
+  },
+
+  /** Begin a broadcast to a channel. */
+  to(channel: string) {
+    return BroadcastManager.to(channel)
+  },
+
+  /** Number of active WebSocket connections. */
+  get clientCount() {
+    return BroadcastManager.clientCount
+  },
+
+  /** Number of subscribers on a specific channel. */
+  subscriberCount(channel: string) {
+    return BroadcastManager.subscriberCount(channel)
+  },
+}

package/src/cache/cache_manager.ts

@@ -0,0 +1,56 @@
+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/core/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/http_cache.ts

@@ -0,0 +1,109 @@
+import type Context from '../http/context.ts'
+import type { Middleware } from '../http/middleware.ts'
+
+export interface HttpCacheOptions {
+  /** Cache-Control max-age in seconds. @default 0 */
+  maxAge?: number
+
+  /** Cache-Control s-maxage for shared caches (CDN). */
+  sMaxAge?: number
+
+  /** Cache-Control directives. @default ['public'] */
+  directives?: CacheDirective[]
+
+  /** Add weak ETag header based on response body hash. @default false */
+  etag?: boolean
+
+  /** Vary header values. @default ['Accept-Encoding'] */
+  vary?: string[]
+
+  /** Skip cache headers for certain requests. */
+  skip?: (ctx: Context) => boolean
+}
+
+export type CacheDirective =
+  | 'public'
+  | 'private'
+  | 'no-cache'
+  | 'no-store'
+  | 'must-revalidate'
+  | 'immutable'
+
+/**
+ * HTTP cache middleware — sets Cache-Control, ETag, and Vary headers.
+ *
+ * Only applies to GET and HEAD requests. Browser/CDN does the actual caching.
+ * When `etag` is enabled and the request includes a matching `If-None-Match`
+ * header, responds with 304 Not Modified.
+ *
+ * @example
+ * router.group({ middleware: [httpCache({ maxAge: 300, etag: true })] }, r => {
+ *   r.get('/api/categories', listCategories)
+ * })
+ */
+export function httpCache(options: HttpCacheOptions = {}): Middleware {
+  const {
+    maxAge = 0,
+    sMaxAge,
+    directives = ['public'],
+    etag: enableEtag = false,
+    vary = ['Accept-Encoding'],
+    skip,
+  } = options
+
+  const cacheControl = buildCacheControl(directives, maxAge, sMaxAge)
+
+  return async (ctx, next) => {
+    // Only cache GET and HEAD responses
+    if (ctx.method !== 'GET' && ctx.method !== 'HEAD') return next()
+
+    if (skip?.(ctx)) return next()
+
+    const response = await next()
+
+    const headers = new Headers(response.headers)
+    headers.set('Cache-Control', cacheControl)
+
+    if (vary.length > 0) {
+      const existing = headers.get('Vary')
+      const merged = existing ? `${existing}, ${vary.join(', ')}` : vary.join(', ')
+      headers.set('Vary', merged)
+    }
+
+    if (enableEtag) {
+      const body = await response.clone().arrayBuffer()
+      const hash = new Bun.CryptoHasher('md5').update(body).digest('hex')
+      const tag = `W/"${hash}"`
+
+      headers.set('ETag', tag)
+
+      const ifNoneMatch = ctx.header('if-none-match')
+      if (ifNoneMatch === tag) {
+        return new Response(null, { status: 304, headers })
+      }
+
+      return new Response(body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+      })
+    }
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    })
+  }
+}
+
+function buildCacheControl(
+  directives: CacheDirective[],
+  maxAge: number,
+  sMaxAge?: number
+): string {
+  const parts = [...directives]
+  if (maxAge > 0) parts.push(`max-age=${maxAge}` as CacheDirective)
+  if (sMaxAge != null) parts.push(`s-maxage=${sMaxAge}` as CacheDirective)
+  return parts.join(', ')
+}

package/src/cache/index.ts

@@ -0,0 +1,6 @@
+export { default as CacheManager } from './cache_manager.ts'
+export { MemoryCacheStore } from './memory_store.ts'
+export { cache } from './helpers.ts'
+export { httpCache } from './http_cache.ts'
+export type { CacheStore, CacheConfig } from './cache_store.ts'
+export type { HttpCacheOptions, CacheDirective } from './http_cache.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/cli/bootstrap.ts

@@ -0,0 +1,37 @@
+import Configuration from '../config/configuration.ts'
+import Database from '../database/database.ts'
+import SchemaRegistry from '../schema/registry.ts'
+import DatabaseIntrospector from '../database/introspector.ts'
+
+export interface BootstrapResult {
+  config: Configuration
+  db: Database
+  registry: SchemaRegistry
+  introspector: DatabaseIntrospector
+}
+
+/**
+ * Bootstrap the core framework services needed by CLI commands.
+ *
+ * Loads configuration, connects to the database, discovers and validates
+ * schemas, and creates an introspector instance.
+ */
+export async function bootstrap(): Promise<BootstrapResult> {
+  const config = new Configuration('./config')
+  await config.load()
+
+  const db = new Database(config)
+
+  const registry = new SchemaRegistry()
+  await registry.discover('database/schemas')
+  registry.validate()
+
+  const introspector = new DatabaseIntrospector(db)
+
+  return { config, db, registry, introspector }
+}
+
+/** Cleanly close the database connection. */
+export async function shutdown(db: Database): Promise<void> {
+  await db.close()
+}

package/src/cli/commands/generate_api.ts

@@ -0,0 +1,74 @@
+import { join } from 'node:path'
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import SchemaRegistry from '../../schema/registry.ts'
+import ApiGenerator from '../../generators/api_generator.ts'
+import RouteGenerator from '../../generators/route_generator.ts'
+import TestGenerator from '../../generators/test_generator.ts'
+import DocGenerator from '../../generators/doc_generator.ts'
+import type { ApiRoutingConfig } from '../../generators/route_generator.ts'
+import type { GeneratorConfig } from '../../generators/config.ts'
+
+export function registerGenerateApi(program: Command): void {
+  program
+    .command('generate:api')
+    .description(
+      'Generate services, controllers, policies, validators, events, and routes from schemas'
+    )
+    .action(async () => {
+      try {
+        console.log(chalk.cyan('Generating API layer from schemas...'))
+
+        const registry = new SchemaRegistry()
+        await registry.discover('database/schemas')
+        registry.validate()
+
+        const schemas = registry.resolve()
+        const representation = registry.buildRepresentation()
+
+        // Load generator config (if available)
+        let config: GeneratorConfig | undefined
+        try {
+          config = (await import(join(process.cwd(), 'config/generators.ts'))).default
+        } catch {
+          // No config/generators.ts — use defaults
+        }
+
+        const apiGen = new ApiGenerator(schemas, representation, config)
+        const apiFiles = await apiGen.writeAll()
+
+        // Load API routing config from config/http.ts (if available)
+        let apiConfig: Partial<ApiRoutingConfig> | undefined
+        try {
+          const httpConfig = (await import(join(process.cwd(), 'config/http.ts'))).default
+          apiConfig = httpConfig.api
+        } catch {
+          // No config/http.ts or no api section — use defaults
+        }
+
+        const routeGen = new RouteGenerator(schemas, config, apiConfig)
+        const routeFiles = await routeGen.writeAll()
+
+        const testGen = new TestGenerator(schemas, representation, config, apiConfig)
+        const testFiles = await testGen.writeAll()
+
+        const docGen = new DocGenerator(schemas, representation, config, apiConfig)
+        const docFiles = await docGen.writeAll()
+
+        const files = [...apiFiles, ...routeFiles, ...testFiles, ...docFiles]
+
+        if (files.length === 0) {
+          console.log(chalk.yellow('No API files to generate.'))
+          return
+        }
+
+        console.log(chalk.green(`\nGenerated ${files.length} file(s):`))
+        for (const file of files) {
+          console.log(chalk.dim(`  ${file.path}`))
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      }
+    })
+}

package/src/cli/commands/generate_key.ts

@@ -0,0 +1,46 @@
+import { join } from 'node:path'
+import type { Command } from 'commander'
+import chalk from 'chalk'
+
+export function registerGenerateKey(program: Command): void {
+  program
+    .command('generate:key')
+    .description('Generate an APP_KEY and write it to the .env file')
+    .option('-f, --force', 'Overwrite existing APP_KEY if present')
+    .action(async ({ force }: { force?: boolean }) => {
+      try {
+        const key = crypto.randomUUID()
+        const envPath = join(process.cwd(), '.env')
+        const file = Bun.file(envPath)
+
+        if (await file.exists()) {
+          const contents = await file.text()
+          const hasKey = /^APP_KEY\s*=/m.test(contents)
+
+          if (hasKey && !force) {
+            const current = contents.match(/^APP_KEY\s*=\s*(.*)$/m)?.[1] ?? ''
+            if (current) {
+              console.log(chalk.yellow('APP_KEY already exists in .env. Use --force to overwrite.'))
+              return
+            }
+          }
+
+          if (hasKey) {
+            const updated = contents.replace(/^APP_KEY\s*=.*$/m, `APP_KEY=${key}`)
+            await Bun.write(envPath, updated)
+          } else {
+            const separator = contents.endsWith('\n') ? '' : '\n'
+            await Bun.write(envPath, contents + separator + `APP_KEY=${key}\n`)
+          }
+        } else {
+          await Bun.write(envPath, `APP_KEY=${key}\n`)
+        }
+
+        console.log(chalk.green('APP_KEY generated successfully.'))
+        console.log(chalk.dim(`  ${key}`))
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      }
+    })
+}

package/src/cli/commands/generate_models.ts

@@ -0,0 +1,48 @@
+import { join } from 'node:path'
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import SchemaRegistry from '../../schema/registry.ts'
+import ModelGenerator from '../../generators/model_generator.ts'
+import type { GeneratorConfig } from '../../generators/config.ts'
+
+export function registerGenerateModels(program: Command): void {
+  program
+    .command('generate:models')
+    .description('Generate model classes and enums from schema definitions')
+    .action(async () => {
+      try {
+        console.log(chalk.cyan('Generating models from schemas...'))
+
+        const registry = new SchemaRegistry()
+        await registry.discover('database/schemas')
+        registry.validate()
+
+        const schemas = registry.resolve()
+        const representation = registry.buildRepresentation()
+
+        // Load generator config (if available)
+        let config: GeneratorConfig | undefined
+        try {
+          config = (await import(join(process.cwd(), 'config/generators.ts'))).default
+        } catch {
+          // No config/generators.ts — use defaults
+        }
+
+        const generator = new ModelGenerator(schemas, representation, config)
+        const files = await generator.writeAll()
+
+        if (files.length === 0) {
+          console.log(chalk.yellow('No models to generate.'))
+          return
+        }
+
+        console.log(chalk.green(`\nGenerated ${files.length} file(s):`))
+        for (const file of files) {
+          console.log(chalk.dim(`  ${file.path}`))
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      }
+    })
+}