@mantiq/core 0.0.1

package/src/hashing/Argon2Hasher.ts

@@ -0,0 +1,46 @@
+import type { Hasher } from '../contracts/Hasher.ts'
+
+export interface Argon2Options {
+  memoryCost: number
+  timeCost: number
+}
+
+const DEFAULTS: Argon2Options = {
+  memoryCost: 65536, // 64 MB
+  timeCost: 4,
+}
+
+/**
+ * Argon2id hasher using Bun.password (zero external deps).
+ */
+export class Argon2Hasher implements Hasher {
+  private readonly memoryCost: number
+  private readonly timeCost: number
+
+  constructor(options?: Partial<Argon2Options>) {
+    this.memoryCost = options?.memoryCost ?? DEFAULTS.memoryCost
+    this.timeCost = options?.timeCost ?? DEFAULTS.timeCost
+  }
+
+  async make(value: string): Promise<string> {
+    return Bun.password.hash(value, {
+      algorithm: 'argon2id',
+      memoryCost: this.memoryCost,
+      timeCost: this.timeCost,
+    })
+  }
+
+  async check(value: string, hashedValue: string): Promise<boolean> {
+    return Bun.password.verify(value, hashedValue, 'argon2id')
+  }
+
+  needsRehash(hashedValue: string): boolean {
+    // Argon2 format: $argon2id$v=19$m=<mem>,t=<time>,p=<par>$...
+    const match = hashedValue.match(/\$argon2id\$v=\d+\$m=(\d+),t=(\d+),/)
+    if (!match) return true
+    return (
+      parseInt(match[1]!, 10) !== this.memoryCost ||
+      parseInt(match[2]!, 10) !== this.timeCost
+    )
+  }
+}

package/src/hashing/BcryptHasher.ts

@@ -0,0 +1,36 @@
+import type { Hasher } from '../contracts/Hasher.ts'
+
+export interface BcryptOptions {
+  rounds: number
+}
+
+const DEFAULT_ROUNDS = 10
+
+/**
+ * Bcrypt hasher using Bun.password (zero external deps).
+ */
+export class BcryptHasher implements Hasher {
+  private readonly rounds: number
+
+  constructor(options?: Partial<BcryptOptions>) {
+    this.rounds = options?.rounds ?? DEFAULT_ROUNDS
+  }
+
+  async make(value: string): Promise<string> {
+    return Bun.password.hash(value, {
+      algorithm: 'bcrypt',
+      cost: this.rounds,
+    })
+  }
+
+  async check(value: string, hashedValue: string): Promise<boolean> {
+    return Bun.password.verify(value, hashedValue, 'bcrypt')
+  }
+
+  needsRehash(hashedValue: string): boolean {
+    // Bcrypt format: $2b$<cost>$...
+    const match = hashedValue.match(/^\$2[aby]\$(\d+)\$/)
+    if (!match) return true
+    return parseInt(match[1]!, 10) !== this.rounds
+  }
+}

package/src/hashing/HashManager.ts

@@ -0,0 +1,80 @@
+import type { Hasher } from '../contracts/Hasher.ts'
+import type { DriverManager } from '../contracts/DriverManager.ts'
+import { BcryptHasher } from './BcryptHasher.ts'
+import { Argon2Hasher } from './Argon2Hasher.ts'
+
+export interface HashConfig {
+  driver: string
+  bcrypt?: { rounds?: number }
+  argon2?: { memoryCost?: number; timeCost?: number }
+}
+
+/**
+ * Multi-driver hash manager (Laravel-style).
+ *
+ * Supports bcrypt and argon2id out of the box.
+ * Custom drivers can be added via `extend()`.
+ */
+export class HashManager implements DriverManager<Hasher>, Hasher {
+  private readonly config: HashConfig
+  private readonly drivers = new Map<string, Hasher>()
+  private readonly customCreators = new Map<string, () => Hasher>()
+
+  constructor(config?: Partial<HashConfig>) {
+    this.config = {
+      driver: config?.driver ?? 'bcrypt',
+      bcrypt: config?.bcrypt ?? {},
+      argon2: config?.argon2 ?? {},
+    }
+  }
+
+  // ── DriverManager ───────────────────────────────────────────────────────
+
+  driver(name?: string): Hasher {
+    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: () => Hasher): void {
+    this.customCreators.set(name, factory)
+  }
+
+  getDefaultDriver(): string {
+    return this.config.driver
+  }
+
+  // ── Hasher (delegates to default driver) ────────────────────────────────
+
+  async make(value: string): Promise<string> {
+    return this.driver().make(value)
+  }
+
+  async check(value: string, hashedValue: string): Promise<boolean> {
+    return this.driver().check(value, hashedValue)
+  }
+
+  needsRehash(hashedValue: string): boolean {
+    return this.driver().needsRehash(hashedValue)
+  }
+
+  // ── Internal ────────────────────────────────────────────────────────────
+
+  private createDriver(name: string): Hasher {
+    const custom = this.customCreators.get(name)
+    if (custom) return custom()
+
+    switch (name) {
+      case 'bcrypt':
+        return new BcryptHasher(this.config.bcrypt)
+      case 'argon2':
+        return new Argon2Hasher(this.config.argon2)
+      default:
+        throw new Error(`Unsupported hash driver: ${name}. Use extend() to register custom drivers.`)
+    }
+  }
+}

package/src/helpers/abort.ts

@@ -0,0 +1,46 @@
+import { HttpError } from '../errors/HttpError.ts'
+import { NotFoundError } from '../errors/NotFoundError.ts'
+import { UnauthorizedError } from '../errors/UnauthorizedError.ts'
+import { ForbiddenError } from '../errors/ForbiddenError.ts'
+import { TooManyRequestsError } from '../errors/TooManyRequestsError.ts'
+
+const STATUS_MESSAGES: Record<number, string> = {
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  403: 'Forbidden',
+  404: 'Not Found',
+  405: 'Method Not Allowed',
+  409: 'Conflict',
+  410: 'Gone',
+  422: 'Unprocessable Entity',
+  429: 'Too Many Requests',
+  500: 'Internal Server Error',
+  503: 'Service Unavailable',
+}
+
+/**
+ * Throw an HTTP exception from anywhere — controllers, middleware, services.
+ *
+ * Uses typed error subclasses where available.
+ *
+ * @throws HttpError (or typed subclass)
+ *
+ * @example abort(404)
+ * @example abort(403, 'You cannot edit this post')
+ * @example abort(429, 'Slow down', { 'Retry-After': '60' })
+ */
+export function abort(
+  status: number,
+  message?: string,
+  headers?: Record<string, string>,
+): never {
+  const msg = message ?? STATUS_MESSAGES[status] ?? 'Error'
+
+  switch (status) {
+    case 401: throw new UnauthorizedError(msg, headers)
+    case 403: throw new ForbiddenError(msg, headers)
+    case 404: throw new NotFoundError(msg, headers)
+    case 429: throw new TooManyRequestsError(msg)
+    default:  throw new HttpError(status, msg, headers)
+  }
+}

package/src/helpers/app.ts

@@ -0,0 +1,17 @@
+import { Application } from '../application/Application.ts'
+import type { Bindable } from '../contracts/Container.ts'
+
+/**
+ * Access the application container, or resolve a binding from it.
+ *
+ * @example app()                    // Returns the Application instance
+ * @example app(Router)              // Resolves the Router from the container
+ * @example app('cache.store')       // Resolves by string alias
+ */
+export function app(): Application
+export function app<T>(abstract: Bindable<T>): T
+export function app<T>(abstract?: Bindable<T>): Application | T {
+  const instance = Application.getInstance()
+  if (abstract === undefined) return instance
+  return instance.make(abstract)
+}

package/src/helpers/cache.ts

@@ -0,0 +1,12 @@
+import { Application } from '../application/Application.ts'
+import { CacheManager } from '../cache/CacheManager.ts'
+
+/**
+ * Access the cache manager or a specific store.
+ *
+ * @example cache()           // default store (CacheManager, proxies to default)
+ * @example cache().store('file')  // specific store
+ */
+export function cache(): CacheManager {
+  return Application.getInstance().make(CacheManager)
+}

package/src/helpers/config.ts

@@ -0,0 +1,15 @@
+import { Application } from '../application/Application.ts'
+
+/**
+ * Access config values from anywhere in the application.
+ *
+ * Reads from the ConfigRepository loaded at bootstrap.
+ * Config is always available after Application.create() — before any provider runs.
+ *
+ * @example config('app.name')
+ * @example config('database.connections.sqlite.path', ':memory:')
+ * @example config<boolean>('app.debug', false)
+ */
+export function config<T = any>(key: string, defaultValue?: T): T {
+  return Application.getInstance().config().get(key, defaultValue)
+}

package/src/helpers/encrypt.ts

@@ -0,0 +1,22 @@
+import { Application } from '../application/Application.ts'
+import type { AesEncrypter } from '../encryption/Encrypter.ts'
+
+export const ENCRYPTER = Symbol('Encrypter')
+
+/**
+ * Encrypt a string value using the application encrypter.
+ *
+ * @example const token = await encrypt('secret-value')
+ */
+export async function encrypt(value: string): Promise<string> {
+  return Application.getInstance().make<AesEncrypter>(ENCRYPTER).encrypt(value)
+}
+
+/**
+ * Decrypt a string value using the application encrypter.
+ *
+ * @example const plain = await decrypt(token)
+ */
+export async function decrypt(value: string): Promise<string> {
+  return Application.getInstance().make<AesEncrypter>(ENCRYPTER).decrypt(value)
+}

package/src/helpers/env.ts

@@ -0,0 +1 @@
+export { env } from '../config/env.ts'

package/src/helpers/hash.ts

@@ -0,0 +1,20 @@
+import { Application } from '../application/Application.ts'
+import { HashManager } from '../hashing/HashManager.ts'
+
+/**
+ * Hash a plain-text value using the default hasher.
+ *
+ * @example const hashed = await hash('password')
+ */
+export async function hash(value: string): Promise<string> {
+  return Application.getInstance().make(HashManager).make(value)
+}
+
+/**
+ * Check a plain-text value against a hash.
+ *
+ * @example if (await hashCheck('password', hashed)) { ... }
+ */
+export async function hashCheck(value: string, hashedValue: string): Promise<boolean> {
+  return Application.getInstance().make(HashManager).check(value, hashedValue)
+}

package/src/helpers/response.ts

@@ -0,0 +1,69 @@
+import { MantiqResponse, ResponseBuilder } from '../http/Response.ts'
+
+/**
+ * Create a chainable response builder.
+ *
+ * @example
+ * response().status(201).cookie('token', 'abc').json({ created: true })
+ */
+export function response(): ResponseBuilder {
+  return new ResponseBuilder()
+}
+
+/**
+ * Return a JSON response.
+ *
+ * @example
+ * return json({ users }, 200)
+ * return json({ error: 'Not found' }, 404)
+ */
+export function json(data: any, status: number = 200, headers?: Record<string, string>): Response {
+  return MantiqResponse.json(data, status, headers)
+}
+
+/**
+ * Return an HTML response.
+ *
+ * @example return html('<h1>Hello</h1>')
+ */
+export function html(content: string, status: number = 200): Response {
+  return MantiqResponse.html(content, status)
+}
+
+/**
+ * Return a redirect response.
+ *
+ * @example return redirect('/dashboard')
+ */
+export function redirect(url: string, status: number = 302): Response {
+  return MantiqResponse.redirect(url, status)
+}
+
+/** Return a 204 No Content response. */
+export function noContent(): Response {
+  return MantiqResponse.noContent()
+}
+
+/**
+ * Return a streaming response.
+ *
+ * @example
+ * return stream((controller) => {
+ *   controller.enqueue('chunk 1')
+ *   controller.close()
+ * })
+ */
+export function stream(
+  callback: (controller: ReadableStreamDefaultController) => void | Promise<void>,
+): Response {
+  return MantiqResponse.stream(callback)
+}
+
+/**
+ * Return a file download response.
+ *
+ * @example return download(buffer, 'report.pdf')
+ */
+export function download(content: Uint8Array | string, filename: string, mimeType?: string): Response {
+  return MantiqResponse.download(content, filename, mimeType)
+}

package/src/helpers/route.ts

@@ -0,0 +1,24 @@
+import { Application } from '../application/Application.ts'
+import type { Router } from '../contracts/Router.ts'
+
+// @internal: Router symbol — the Router implementation binds itself under this key
+export const ROUTER = Symbol('Router')
+
+/**
+ * Generate a URL for a named route.
+ *
+ * @param name - The route name (e.g., 'users.show')
+ * @param params - Route parameters (e.g., { id: 1 })
+ * @param absolute - If true, prepends APP_URL to make an absolute URL
+ *
+ * @example route('users.show', { id: 42 })           // '/users/42'
+ * @example route('users.show', { id: 42 }, true)     // 'http://localhost:3000/users/42'
+ */
+export function route(
+  name: string,
+  params?: Record<string, any>,
+  absolute: boolean = false,
+): string {
+  const router = Application.getInstance().make<Router>(ROUTER)
+  return router.url(name, params, absolute)
+}

package/src/helpers/session.ts

@@ -0,0 +1,11 @@
+import { Application } from '../application/Application.ts'
+import { SessionManager } from '../session/SessionManager.ts'
+
+/**
+ * Access the session manager.
+ *
+ * @example session()  // SessionManager instance
+ */
+export function session(): SessionManager {
+  return Application.getInstance().make(SessionManager)
+}

package/src/http/Cookie.ts

@@ -0,0 +1,26 @@
+import type { CookieOptions } from '../contracts/Response.ts'
+
+export function parseCookies(cookieHeader: string | null): Record<string, string> {
+  if (!cookieHeader) return {}
+
+  return Object.fromEntries(
+    cookieHeader.split(';').map((pair) => {
+      const [key, ...rest] = pair.trim().split('=')
+      return [key?.trim() ?? '', decodeURIComponent(rest.join('='))]
+    }),
+  )
+}
+
+export function serializeCookie(name: string, value: string, options: CookieOptions = {}): string {
+  let str = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`
+
+  if (options.maxAge !== undefined) str += `; Max-Age=${options.maxAge}`
+  if (options.expires) str += `; Expires=${options.expires.toUTCString()}`
+  if (options.path) str += `; Path=${options.path}`
+  if (options.domain) str += `; Domain=${options.domain}`
+  if (options.secure) str += '; Secure'
+  if (options.httpOnly) str += '; HttpOnly'
+  if (options.sameSite) str += `; SameSite=${options.sameSite}`
+
+  return str
+}