@mantiq/core 0.0.1

package/src/routing/Router.ts

@@ -0,0 +1,280 @@
+import type {
+  HttpMethod,
+  RouteAction,
+  RouteDefinition,
+  RouteGroupOptions,
+  RouteMatch,
+  Router as RouterContract,
+  RouterRoute,
+} from '../contracts/Router.ts'
+import type { Constructor } from '../contracts/Container.ts'
+import type { MantiqRequest } from '../contracts/Request.ts'
+import type { EventDispatcher } from '../contracts/EventDispatcher.ts'
+import { Route } from './Route.ts'
+import { RouteCollection } from './RouteCollection.ts'
+import { RouteMatcher } from './RouteMatcher.ts'
+import { ResourceRegistrar } from './ResourceRegistrar.ts'
+import { NotFoundError } from '../errors/NotFoundError.ts'
+import { HttpError } from '../errors/HttpError.ts'
+import { MantiqError } from '../errors/MantiqError.ts'
+import { ConfigRepository } from '../config/ConfigRepository.ts'
+import { RouteMatched } from './events.ts'
+
+export class RouterImpl implements RouterContract {
+  private collection = new RouteCollection()
+  private registrar = new ResourceRegistrar(this)
+  private modelBindings = new Map<string, Constructor<any>>()
+  private customBindings = new Map<string, (value: string) => Promise<any>>()
+  private controllerRegistry = new Map<string, Constructor<any>>()
+
+  /** Optional event dispatcher. Set by @mantiq/events when installed. */
+  static _dispatcher: EventDispatcher | null = null
+
+  /** Stack of active group option frames */
+  private groupStack: RouteGroupOptions[] = []
+
+  constructor(private readonly config?: ConfigRepository) {}
+
+  /**
+   * Register controller classes for string-based route actions.
+   *
+   * @example
+   * router.controllers({
+   *   AuthController,
+   *   HomeController,
+   *   UserController,
+   * })
+   *
+   * // Then in routes:
+   * router.get('/login', 'AuthController@login')
+   * router.get('/', 'HomeController@index')
+   */
+  controllers(map: Record<string, Constructor<any>>): void {
+    for (const [name, ctor] of Object.entries(map)) {
+      this.controllerRegistry.set(name, ctor)
+    }
+  }
+
+  // ── HTTP method registration ───────────────────────────────────────────────
+
+  get(path: string, action: RouteAction): RouterRoute {
+    return this.addRoute(['GET'], path, action)
+  }
+
+  post(path: string, action: RouteAction): RouterRoute {
+    return this.addRoute(['POST'], path, action)
+  }
+
+  put(path: string, action: RouteAction): RouterRoute {
+    return this.addRoute(['PUT'], path, action)
+  }
+
+  patch(path: string, action: RouteAction): RouterRoute {
+    return this.addRoute(['PATCH'], path, action)
+  }
+
+  delete(path: string, action: RouteAction): RouterRoute {
+    return this.addRoute(['DELETE'], path, action)
+  }
+
+  options(path: string, action: RouteAction): RouterRoute {
+    return this.addRoute(['OPTIONS'], path, action)
+  }
+
+  match(methods: HttpMethod[], path: string, action: RouteAction): RouterRoute {
+    return this.addRoute(methods, path, action)
+  }
+
+  any(path: string, action: RouteAction): RouterRoute {
+    return this.addRoute(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'], path, action)
+  }
+
+  // ── Resource routes ────────────────────────────────────────────────────────
+
+  resource(name: string, controller: Constructor<any>): void {
+    this.registrar.register(name, controller, false)
+  }
+
+  apiResource(name: string, controller: Constructor<any>): void {
+    this.registrar.register(name, controller, true)
+  }
+
+  // ── Groups ────────────────────────────────────────────────────────────────
+
+  group(options: RouteGroupOptions, callback: (router: RouterContract) => void): void {
+    this.groupStack.push(options)
+    callback(this)
+    this.groupStack.pop()
+  }
+
+  // ── URL generation ─────────────────────────────────────────────────────────
+
+  url(name: string, params: Record<string, any> = {}, absolute = false): string {
+    const route = this.collection.getByName(name)
+    if (!route) {
+      throw new MantiqError(`Route '${name}' not found.`)
+    }
+
+    let path = route.path
+    const usedParams = new Set<string>()
+
+    // Replace :param segments
+    path = path.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)(\?)?/g, (_, paramName: string, optional: string) => {
+      if (params[paramName] !== undefined) {
+        usedParams.add(paramName)
+        return encodeURIComponent(String(params[paramName]))
+      }
+      if (optional) return ''
+      throw new MantiqError(
+        `Missing required parameter '${paramName}' for route '${name}'.`,
+      )
+    })
+
+    // Append remaining params as query string
+    const remaining = Object.entries(params)
+      .filter(([k]) => !usedParams.has(k))
+    if (remaining.length > 0) {
+      path += '?' + new URLSearchParams(
+        Object.fromEntries(remaining.map(([k, v]) => [k, String(v)])),
+      ).toString()
+    }
+
+    if (absolute) {
+      const base = this.config?.get('app.url', 'http://localhost:3000') ?? 'http://localhost:3000'
+      return `${base}${path}`
+    }
+
+    return path
+  }
+
+  // ── Route matching ─────────────────────────────────────────────────────────
+
+  resolve(request: MantiqRequest): RouteMatch {
+    const method = request.method() as HttpMethod
+    const pathname = request.path()
+
+    // Try to match against routes for this method
+    const candidates = this.collection.getByMethod(method)
+
+    for (const route of candidates) {
+      const result = RouteMatcher.match(route, pathname)
+      if (result) {
+        RouterImpl._dispatcher?.emit(new RouteMatched(route.routeName, route.action, request))
+        return {
+          action: route.action,
+          params: result.params,
+          middleware: route.middlewareList,
+          routeName: route.routeName,
+        }
+      }
+    }
+
+    // Check if path exists under a different method → 405
+    const allMethods: HttpMethod[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']
+    const allowedMethods: HttpMethod[] = []
+
+    for (const m of allMethods) {
+      if (m === method) continue
+      const others = this.collection.getByMethod(m)
+      for (const route of others) {
+        if (RouteMatcher.match(route, pathname)) {
+          allowedMethods.push(m)
+          break
+        }
+      }
+    }
+
+    if (allowedMethods.length > 0) {
+      throw new HttpError(405, 'Method Not Allowed', {
+        Allow: allowedMethods.join(', '),
+      })
+    }
+
+    throw new NotFoundError(`No route found for ${method} ${pathname}`)
+  }
+
+  routes(): RouteDefinition[] {
+    return this.collection.all().map((r) => ({
+      method: r.methods.length === 1 ? r.methods[0]! : r.methods,
+      path: r.path,
+      action: r.action,
+      name: r.routeName,
+      middleware: r.middlewareList,
+      wheres: r.wheres,
+    }))
+  }
+
+  // ── Model bindings ─────────────────────────────────────────────────────────
+
+  model(param: string, model: Constructor<any>): void {
+    this.modelBindings.set(param, model)
+  }
+
+  bind(param: string, resolver: (value: string) => Promise<any>): void {
+    this.customBindings.set(param, resolver)
+  }
+
+  // ── Private helpers ────────────────────────────────────────────────────────
+
+  private addRoute(methods: HttpMethod[], path: string, action: RouteAction): Route {
+    const mergedPath = this.mergePath(path)
+    const resolvedAction = this.resolveAction(action)
+    const route = new Route(methods, mergedPath, resolvedAction)
+
+    // Apply group middleware
+    const groupMiddleware = this.groupStack.flatMap((g) => g.middleware ?? [])
+    if (groupMiddleware.length > 0) route.middleware(...groupMiddleware)
+
+    // Always wrap name() so the collection's name index is updated when .name() is called
+    // after add() (which is the normal usage: router.get(...).name('foo'))
+    const namePrefix = this.groupStack.map((g) => g.as ?? '').join('')
+    const originalName = route.name.bind(route)
+    route.name = (n: string) => {
+      originalName(namePrefix + n)
+      this.collection.indexName(route)
+      return route
+    }
+
+    this.collection.add(route)
+    return route
+  }
+
+  /**
+   * Resolve a string action like 'AuthController@login' to [Constructor, method].
+   */
+  private resolveAction(action: RouteAction): Exclude<RouteAction, string> {
+    if (typeof action !== 'string') return action
+
+    const [controllerName, method] = action.split('@')
+    if (!controllerName || !method) {
+      throw new MantiqError(
+        `Invalid route action string '${action}'. Expected format: 'ControllerName@method'.`,
+      )
+    }
+
+    // Check namespace prefix from group stack
+    const namespace = this.groupStack
+      .map((g) => g.namespace ?? '')
+      .filter(Boolean)
+      .join('/')
+
+    const fullName = namespace ? `${namespace}/${controllerName}` : controllerName
+    const Controller = this.controllerRegistry.get(fullName)
+      ?? this.controllerRegistry.get(controllerName)
+
+    if (!Controller) {
+      throw new MantiqError(
+        `Controller '${controllerName}' not found. Register it with router.controllers({ ${controllerName} }).`,
+      )
+    }
+
+    return [Controller, method]
+  }
+
+  private mergePath(path: string): string {
+    const prefixes = this.groupStack.map((g) => g.prefix ?? '').filter(Boolean)
+    if (prefixes.length === 0) return path
+    const prefix = prefixes.join('')
+    return prefix + (path.startsWith('/') ? path : `/${path}`)
+  }
+}

package/src/routing/events.ts

@@ -0,0 +1,19 @@
+import { Event } from '../contracts/EventDispatcher.ts'
+import type { RouteAction } from '../contracts/Router.ts'
+import type { MantiqRequest } from '../contracts/Request.ts'
+
+/**
+ * Fired when the router successfully matches a request to a route.
+ */
+export class RouteMatched extends Event {
+  constructor(
+    /** The matched route name (if named). */
+    public readonly routeName: string | undefined,
+    /** The matched route action. */
+    public readonly action: RouteAction,
+    /** The request that was matched. */
+    public readonly request: MantiqRequest,
+  ) {
+    super()
+  }
+}

package/src/session/SessionManager.ts

@@ -0,0 +1,75 @@
+import type { SessionHandler, SessionConfig } from '../contracts/Session.ts'
+import type { DriverManager } from '../contracts/DriverManager.ts'
+import { MemorySessionHandler } from './handlers/MemorySessionHandler.ts'
+import { FileSessionHandler } from './handlers/FileSessionHandler.ts'
+import { CookieSessionHandler } from './handlers/CookieSessionHandler.ts'
+
+const SESSION_DEFAULTS: SessionConfig = {
+  driver: 'memory',
+  lifetime: 120,
+  cookie: 'mantiq_session',
+  path: '/',
+  secure: false,
+  httpOnly: true,
+  sameSite: 'Lax',
+}
+
+/**
+ * Multi-driver session manager (Laravel-style).
+ *
+ * Built-in drivers: memory, file, cookie.
+ * Custom drivers via `extend()`.
+ */
+export class SessionManager implements DriverManager<SessionHandler> {
+  private readonly config: SessionConfig
+  private readonly drivers = new Map<string, SessionHandler>()
+  private readonly customCreators = new Map<string, () => SessionHandler>()
+
+  constructor(config?: Partial<SessionConfig>) {
+    this.config = { ...SESSION_DEFAULTS, ...config }
+  }
+
+  // ── DriverManager ───────────────────────────────────────────────────────
+
+  driver(name?: string): SessionHandler {
+    const driverName = name ?? this.getDefaultDriver()
+
+    if (!this.drivers.has(driverName)) {
+      this.drivers.set(driverName, this.createDriver(driverName))
+    }
+
+    return this.drivers.get(driverName)!
+  }
+
+  extend(name: string, factory: () => SessionHandler): void {
+    this.customCreators.set(name, factory)
+  }
+
+  getDefaultDriver(): string {
+    return this.config.driver
+  }
+
+  // ── Config access ───────────────────────────────────────────────────────
+
+  getConfig(): Readonly<SessionConfig> {
+    return this.config
+  }
+
+  // ── Internal ────────────────────────────────────────────────────────────
+
+  private createDriver(name: string): SessionHandler {
+    const custom = this.customCreators.get(name)
+    if (custom) return custom()
+
+    switch (name) {
+      case 'memory':
+        return new MemorySessionHandler()
+      case 'file':
+        return new FileSessionHandler(this.config.files ?? '/tmp/mantiq-sessions')
+      case 'cookie':
+        return new CookieSessionHandler()
+      default:
+        throw new Error(`Unsupported session driver: ${name}. Use extend() to register custom drivers.`)
+    }
+  }
+}

package/src/session/Store.ts

@@ -0,0 +1,192 @@
+import type { SessionHandler } from '../contracts/Session.ts'
+
+/**
+ * Session store — holds key/value data for one session.
+ * Reads from and writes to a SessionHandler (driver).
+ */
+export class SessionStore {
+  private id: string
+  private attributes: Record<string, unknown> = {}
+  private started = false
+
+  constructor(
+    private readonly name: string,
+    private readonly handler: SessionHandler,
+    id?: string,
+  ) {
+    this.id = id ?? SessionStore.generateId()
+  }
+
+  /**
+   * Start the session — loads data from the handler.
+   */
+  async start(): Promise<boolean> {
+    const data = await this.handler.read(this.id)
+
+    if (data) {
+      try {
+        this.attributes = JSON.parse(data)
+      } catch {
+        this.attributes = {}
+      }
+    }
+
+    this.started = true
+    return true
+  }
+
+  /**
+   * Save the session — writes data to the handler.
+   */
+  async save(): Promise<void> {
+    await this.handler.write(this.id, JSON.stringify(this.attributes))
+    this.started = false
+  }
+
+  // ── Getters & setters ───────────────────────────────────────────────────
+
+  get<T = unknown>(key: string, defaultValue?: T): T {
+    return (this.attributes[key] as T) ?? (defaultValue as T)
+  }
+
+  put(key: string, value: unknown): void {
+    this.attributes[key] = value
+  }
+
+  has(key: string): boolean {
+    return key in this.attributes
+  }
+
+  forget(key: string): void {
+    delete this.attributes[key]
+  }
+
+  pull<T = unknown>(key: string, defaultValue?: T): T {
+    const value = this.get<T>(key, defaultValue)
+    this.forget(key)
+    return value
+  }
+
+  all(): Record<string, unknown> {
+    return { ...this.attributes }
+  }
+
+  replace(attributes: Record<string, unknown>): void {
+    this.attributes = { ...this.attributes, ...attributes }
+  }
+
+  flush(): void {
+    this.attributes = {}
+  }
+
+  // ── Flash data ──────────────────────────────────────────────────────────
+
+  flash(key: string, value: unknown): void {
+    this.put(key, value)
+    const newFlash = this.get<string[]>('_flash.new', [])
+    if (!newFlash.includes(key)) newFlash.push(key)
+    this.put('_flash.new', newFlash)
+  }
+
+  reflash(): void {
+    const old = this.get<string[]>('_flash.old', [])
+    const newFlash = this.get<string[]>('_flash.new', [])
+    this.put('_flash.new', [...new Set([...newFlash, ...old])])
+    this.put('_flash.old', [])
+  }
+
+  keep(...keys: string[]): void {
+    const old = this.get<string[]>('_flash.old', [])
+    const newFlash = this.get<string[]>('_flash.new', [])
+    const toKeep = keys.length > 0 ? keys : old
+    this.put('_flash.new', [...new Set([...newFlash, ...toKeep])])
+    this.put('_flash.old', old.filter((k) => !toKeep.includes(k)))
+  }
+
+  /**
+   * Age the flash data — called at the end of each request.
+   * Moves "new" flash keys to "old", and removes previously old keys.
+   */
+  ageFlashData(): void {
+    const old = this.get<string[]>('_flash.old', [])
+    for (const key of old) {
+      this.forget(key)
+    }
+    this.put('_flash.old', this.get<string[]>('_flash.new', []))
+    this.put('_flash.new', [])
+  }
+
+  // ── CSRF Token ──────────────────────────────────────────────────────────
+
+  token(): string {
+    if (!this.has('_token')) {
+      this.regenerateToken()
+    }
+    return this.get<string>('_token')!
+  }
+
+  regenerateToken(): void {
+    const bytes = new Uint8Array(40)
+    crypto.getRandomValues(bytes)
+    let token = ''
+    for (let i = 0; i < bytes.length; i++) {
+      token += bytes[i]!.toString(16).padStart(2, '0')
+    }
+    this.put('_token', token)
+  }
+
+  // ── Session ID management ──────────────────────────────────────────────
+
+  getId(): string {
+    return this.id
+  }
+
+  setId(id: string): void {
+    this.id = id
+  }
+
+  getName(): string {
+    return this.name
+  }
+
+  isStarted(): boolean {
+    return this.started
+  }
+
+  /**
+   * Regenerate the session ID (e.g. after login to prevent fixation).
+   */
+  async regenerate(destroy = false): Promise<void> {
+    if (destroy) {
+      await this.handler.destroy(this.id)
+    }
+    this.id = SessionStore.generateId()
+  }
+
+  /**
+   * Invalidate + regenerate: flush all data AND get a new ID.
+   */
+  async invalidate(): Promise<void> {
+    this.flush()
+    await this.regenerate(true)
+  }
+
+  /**
+   * Return the serialized session data (for cookie driver).
+   */
+  serialize(): string {
+    return JSON.stringify(this.attributes)
+  }
+
+  // ── Static helpers ──────────────────────────────────────────────────────
+
+  static generateId(): string {
+    const bytes = new Uint8Array(20)
+    crypto.getRandomValues(bytes)
+    let id = ''
+    for (let i = 0; i < bytes.length; i++) {
+      id += bytes[i]!.toString(16).padStart(2, '0')
+    }
+    return id
+  }
+}

package/src/session/handlers/CookieSessionHandler.ts

@@ -0,0 +1,42 @@
+import type { SessionHandler } from '../../contracts/Session.ts'
+
+/**
+ * Cookie-based session handler.
+ * Session data is stored entirely in the cookie (encrypted by the middleware).
+ * No server-side storage needed — ideal for stateless deployments.
+ *
+ * Size limit: ~4KB per cookie. Suitable for small session payloads.
+ */
+export class CookieSessionHandler implements SessionHandler {
+  private data = new Map<string, string>()
+
+  async read(sessionId: string): Promise<string> {
+    return this.data.get(sessionId) ?? ''
+  }
+
+  async write(sessionId: string, data: string): Promise<void> {
+    this.data.set(sessionId, data)
+  }
+
+  async destroy(sessionId: string): Promise<void> {
+    this.data.delete(sessionId)
+  }
+
+  async gc(_maxLifetimeSeconds: number): Promise<void> {
+    // No-op — cookie expiration is handled by the browser
+  }
+
+  /**
+   * Get the raw data for the session (used by StartSession to write into cookie).
+   */
+  getDataForCookie(sessionId: string): string {
+    return this.data.get(sessionId) ?? ''
+  }
+
+  /**
+   * Seed session data from cookie value (called before session.start()).
+   */
+  setDataFromCookie(sessionId: string, data: string): void {
+    this.data.set(sessionId, data)
+  }
+}

package/src/session/handlers/FileSessionHandler.ts

@@ -0,0 +1,79 @@
+import type { SessionHandler } from '../../contracts/Session.ts'
+import { join } from 'node:path'
+import { mkdir, readdir, rm, stat } from 'node:fs/promises'
+
+/**
+ * File-based session handler. Each session is a JSON file.
+ * Survives process restarts. Good for single-server deployments.
+ */
+export class FileSessionHandler implements SessionHandler {
+  private readonly directory: string
+  private initialized = false
+
+  constructor(directory: string) {
+    this.directory = directory
+  }
+
+  async read(sessionId: string): Promise<string> {
+    await this.ensureDirectory()
+    const file = Bun.file(this.path(sessionId))
+
+    if (!(await file.exists())) return ''
+
+    try {
+      return await file.text()
+    } catch {
+      return ''
+    }
+  }
+
+  async write(sessionId: string, data: string): Promise<void> {
+    await this.ensureDirectory()
+    await Bun.write(this.path(sessionId), data)
+  }
+
+  async destroy(sessionId: string): Promise<void> {
+    try {
+      await rm(this.path(sessionId))
+    } catch {
+      // File might not exist — that's fine
+    }
+  }
+
+  async gc(maxLifetimeSeconds: number): Promise<void> {
+    try {
+      const files = await readdir(this.directory)
+      const cutoff = Date.now() - maxLifetimeSeconds * 1000
+
+      await Promise.all(
+        files
+          .filter((f) => f.endsWith('.session'))
+          .map(async (f) => {
+            const filePath = join(this.directory, f)
+            try {
+              const s = await stat(filePath)
+              if (s.mtimeMs < cutoff) {
+                await rm(filePath)
+              }
+            } catch {
+              // Ignore stat errors
+            }
+          }),
+      )
+    } catch {
+      // Directory might not exist
+    }
+  }
+
+  private path(sessionId: string): string {
+    // Validate session ID to prevent directory traversal
+    const safe = sessionId.replace(/[^a-f0-9]/g, '')
+    return join(this.directory, `${safe}.session`)
+  }
+
+  private async ensureDirectory(): Promise<void> {
+    if (this.initialized) return
+    await mkdir(this.directory, { recursive: true })
+    this.initialized = true
+  }
+}