bunigniter 0.2.0

package/dist/helpers/mail.ts

@@ -0,0 +1,272 @@
+/**
+ * Mail — email sending with SMTP, File, and Null transports.
+ *
+ * @example
+ * ```ts
+ * // In a controller
+ * await this.mail.send({
+ *   to: 'user@test.com',
+ *   subject: 'Welcome!',
+ *   html: '<h1>Hello</h1>',
+ * })
+ *
+ * // With a transport
+ * await this.mail.transport('smtp').send({
+ *   to: 'user@test.com',
+ *   subject: 'Hi',
+ *   text: 'Hello world',
+ * })
+ * ```
+ */
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { env } from './env'
+
+// ─── Types ─────────────────────────────────────────────────────
+
+export interface MailMessage {
+	to: string | string[]
+	from?: string
+	subject: string
+	text?: string
+	html?: string
+	cc?: string | string[]
+	bcc?: string | string[]
+	replyTo?: string
+	attachments?: MailAttachment[]
+	headers?: Record<string, string>
+}
+
+export interface MailAttachment {
+	filename: string
+	content: Buffer | string
+	contentType?: string
+}
+
+export interface MailOptions {
+	/** Default from address. */
+	defaultFrom?: string
+
+	/** Default transport. */
+	transport?: MailTransport
+
+	/** Storage directory for file transport. Default: 'storage/mail' */
+	storageDir?: string
+}
+
+// ─── Transports ─────────────────────────────────────────────────
+
+export interface MailTransport {
+	name: string
+	send(message: MailMessage): Promise<void>
+}
+
+/**
+ * Null transport — discards all messages (for testing).
+ */
+export class NullTransport implements MailTransport {
+	name = 'null'
+	async send(_message: MailMessage): Promise<void> {
+		// Discard
+	}
+}
+
+/**
+ * File transport — writes messages to disk (for development).
+ */
+export class FileTransport implements MailTransport {
+	name = 'file'
+	private dir: string
+
+	constructor(dir?: string) {
+		this.dir = dir ?? join(process.cwd(), 'storage/mail')
+	}
+
+	async send(message: MailMessage): Promise<void> {
+		if (!existsSync(this.dir)) {
+			mkdirSync(this.dir, { recursive: true })
+		}
+
+		const filename = `${Date.now()}_${message.subject.replace(/[^a-zA-Z0-9]/g, '_').slice(0, 50)}.json`
+		const content = JSON.stringify(message, null, 2)
+		writeFileSync(join(this.dir, filename), content, 'utf-8')
+	}
+}
+
+/**
+ * SMTP transport — sends via SMTP server.
+ * Uses Bun's built-in SMTP or a lightweight client.
+ */
+export class SmtpTransport implements MailTransport {
+	name = 'smtp'
+	private host: string
+	private port: number
+	private user: string
+	private pass: string
+	private secure: boolean
+
+	constructor(options: {
+		host?: string
+		port?: number
+		user?: string
+		pass?: string
+		secure?: boolean
+	} = {}) {
+		this.host = options.host ?? env('SMTP_HOST', 'localhost')
+		this.port = options.port ?? Number(env('SMTP_PORT', '587'))
+		this.user = options.user ?? env('SMTP_USER', '')
+		this.pass = options.pass ?? env('SMTP_PASS', '')
+		this.secure = options.secure ?? env('SMTP_SECURE', false)
+	}
+
+	async send(message: MailMessage): Promise<void> {
+		// Build email content
+		const from = message.from ?? env('MAIL_FROM', 'noreply@localhost')
+		const to = Array.isArray(message.to) ? message.to.join(', ') : message.to
+
+		let headers = `From: ${from}\nTo: ${to}\nSubject: ${message.subject}\n`
+		if (message.cc) {
+			headers += `Cc: ${Array.isArray(message.cc) ? message.cc.join(', ') : message.cc}\n`
+		}
+		if (message.replyTo) {
+			headers += `Reply-To: ${message.replyTo}\n`
+		}
+		headers += 'MIME-Version: 1.0\n'
+
+		let body = ''
+		if (message.html) {
+			headers += 'Content-Type: text/html; charset=UTF-8\n'
+			body = message.html
+		} else if (message.text) {
+			headers += 'Content-Type: text/plain; charset=UTF-8\n'
+			body = message.text
+		}
+
+		const raw = `${headers}\n${body}`
+
+		// Send via SMTP using Bun's TCP socket
+		try {
+			const { connect } = await import('node:net')
+			await new Promise<void>((resolve, reject) => {
+				const socket = connect(this.port, this.host, () => {
+					let buffer = ''
+					let step = 0
+
+					const send = (cmd: string) => {
+						socket.write(cmd + '\r\n')
+					}
+
+					socket.on('data', (data: Buffer) => {
+						buffer += data.toString()
+						const lines = buffer.split('\r\n')
+						buffer = lines.pop() ?? ''
+
+						for (const line of lines) {
+							if (line.startsWith('220') && step === 0) {
+								step = 1
+								send(`EHLO ${this.host}`)
+							} else if (line.startsWith('250') && step === 1) {
+								if (this.user && this.pass) {
+									step = 2
+									send('AUTH LOGIN')
+								} else {
+									step = 3
+									send(`MAIL FROM:<${from}>`)
+								}
+							} else if (line.startsWith('334') && step === 2) {
+								send(Buffer.from(this.user).toString('base64'))
+								step = 21
+							} else if (line.startsWith('334') && step === 21) {
+								send(Buffer.from(this.pass).toString('base64'))
+								step = 22
+							} else if (line.startsWith('235') && step === 22) {
+								step = 3
+								send(`MAIL FROM:<${from}>`)
+							} else if (line.startsWith('250') && step === 3) {
+								step = 4
+								send(`RCPT TO:<${to}>`)
+							} else if (line.startsWith('250') && step === 4) {
+								step = 5
+								send('DATA')
+							} else if (line.startsWith('354') && step === 5) {
+								step = 6
+								send(raw + '\r\n.')
+							} else if (line.startsWith('250') && step === 6) {
+								step = 7
+								send('QUIT')
+							} else if (line.startsWith('221') && step === 7) {
+								socket.end()
+								resolve()
+							}
+						}
+					})
+
+					socket.on('error', reject)
+				})
+
+				setTimeout(() => {
+					socket.destroy()
+					reject(new Error('SMTP connection timed out'))
+				}, 10000)
+			})
+		} catch (err) {
+			// Fall back to file transport on error
+			const fallback = new FileTransport(this.dir)
+			await fallback.send(message)
+		}
+	}
+
+	private get dir(): string {
+		return join(process.cwd(), 'storage/mail')
+	}
+}
+
+// ─── Mail Service ───────────────────────────────────────────────
+
+/**
+ * Mail service — send emails with configurable transport.
+ *
+ * Usage in a Controller:
+ * ```ts
+ * await this.mail.send({
+ *   to: 'user@test.com',
+ *   subject: 'Welcome!',
+ *   html: '<h1>Hello</h1>',
+ * })
+ * ```
+ */
+export class Mail {
+	private options: MailOptions
+	private _transport: MailTransport
+
+	constructor(options: MailOptions = {}) {
+		this.options = options
+		this._transport = options.transport ?? new NullTransport()
+	}
+
+	/**
+	 * Send an email.
+	 */
+	async send(message: MailMessage): Promise<void> {
+		const msg: MailMessage = {
+			...message,
+			from: message.from ?? this.options.defaultFrom ?? env('MAIL_FROM', 'noreply@localhost'),
+		}
+		await this._transport.send(msg)
+	}
+
+	/**
+	 * Send with a specific transport (one-off override).
+	 */
+	async transport(transport: MailTransport): Promise<void> {
+		this._transport = transport
+	}
+}
+
+let _mailInstance: Mail | null = null
+export function createMail(options?: MailOptions): Mail {
+	if (!_mailInstance) {
+		_mailInstance = new Mail(options)
+	}
+	return _mailInstance
+}

package/dist/helpers/middleware-loader.ts

@@ -0,0 +1,116 @@
+/**
+ * Middleware Loader — Void-style file-based middleware directory.
+ *
+ * Place files in `middleware/` with numeric prefixes for ordering:
+ * ```
+ * middleware/
+ * ├── 01.logger.ts     ← runs first
+ * ├── 02.auth.ts       ← runs second
+ * ├── 03.cors.ts       ← runs third
+ * └── _helpers.ts      ← ignored (starts with _)
+ * ```
+ *
+ * Each file exports a default middleware function:
+ * ```ts
+ * // middleware/01.request-id.ts
+ * import { defineMiddleware } from 'nexusts'
+ *
+ * export default defineMiddleware(async (c, next) => {
+ *   const start = performance.now()
+ *   await next()
+ *   c.header('X-Response-Time', `${performance.now() - start}ms`)
+ * })
+ * ```
+ *
+ * Middleware can set context variables via c.set():
+ * ```ts
+ * declare module 'elysia' {
+ *   interface ElysiaContext {
+ *     requestId: string
+ *   }
+ * }
+ * ```
+ */
+import { readdirSync, statSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { Elysia } from 'elysia'
+
+/** Middleware function signature (Hono-compatible). */
+export type MiddlewareFn = (c: any, next: () => Promise<void>) => Promise<void> | void
+
+/**
+ * Define middleware with proper typing.
+ *
+ * @example
+ * ```ts
+ * // middleware/01.logger.ts
+ * import { defineMiddleware } from 'nexusts'
+ *
+ * export default defineMiddleware(async (c, next) => {
+ *   console.log(c.request.method, c.request.url)
+ *   await next()
+ * })
+ * ```
+ */
+export function defineMiddleware(fn: MiddlewareFn): MiddlewareFn {
+	return fn
+}
+
+/** Loaded middleware entry. */
+interface MiddlewareEntry {
+	name: string
+	order: number
+	fn: MiddlewareFn
+}
+
+/**
+ * Load and apply middleware from the `middleware/` directory.
+ *
+ * Files starting with `_` are ignored.
+ * Files with numeric prefixes (e.g. `01_logger.ts`) are sorted by prefix.
+ * Files without numeric prefix are loaded alphabetically after numbered ones.
+ *
+ * @param dir - Middleware directory path. Default: 'middleware'
+ */
+export async function loadMiddleware(dir: string = 'middleware'): Promise<MiddlewareFn[]> {
+	if (!existsSync(dir)) return []
+
+	const entries: MiddlewareEntry[] = []
+	const files = readdirSync(dir, { withFileTypes: true })
+
+	for (const file of files) {
+		if (!file.isFile() || !file.name.endsWith('.ts') || file.name.startsWith('_')) continue
+
+		const fullPath = join(process.cwd(), dir, file.name)
+		const mod = await import(fullPath)
+		const fn = mod.default ?? mod.middleware
+		if (typeof fn !== 'function') continue
+
+		// Extract numeric prefix (e.g. "01" from "01_logger.ts")
+		const match = file.name.match(/^(\d+)[._-]/)
+		const order = match ? parseInt(match[1], 10) : 999
+
+		entries.push({
+			name: file.name.replace(/\.ts$/, ''),
+			order,
+			fn,
+		})
+	}
+
+	// Sort by order, then by name for stability
+	entries.sort((a, b) => a.order - b.order || a.name.localeCompare(b.name))
+
+	return entries.map(e => e.fn)
+}
+
+/**
+ * Apply middleware to an Elysia app.
+ * Uses Elysia v2's `request()` lifecycle hook.
+ */
+export function applyMiddlewareToApp(app: Elysia, middleware: MiddlewareFn[]): void {
+	for (const fn of middleware) {
+		app.request(async (ctx: any) => {
+			await fn(ctx, async () => {})
+		})
+	}
+}

package/dist/helpers/middleware.ts

@@ -0,0 +1,57 @@
+/**
+ * Middleware loader — applies configured middleware to an Elysia app.
+ *
+ * Reads from config/app.ts and applies middleware in order.
+ *
+ * @example
+ * ```ts
+ * // src/index.ts
+ * import { applyMiddleware } from './helpers/middleware'
+ * applyMiddleware(app, config.middleware)
+ * ```
+ */
+import { Elysia } from 'elysia'
+import { corsMiddleware, type CORSOptions } from './cors'
+import { loggerMiddleware, type LoggerOptions } from './logger'
+import { csrfMiddleware, type CSRFOptions } from './csrf'
+import { rateLimiter, type ThrottleOptions } from './throttle'
+
+/** Middleware configuration from config/app.ts. */
+export interface MiddlewareConfig {
+	/** CORS settings. false to disable. */
+	cors?: CORSOptions | false
+
+	/** Logger settings. false to disable. */
+	logger?: LoggerOptions | false
+
+	/** CSRF protection. false to disable. */
+	csrf?: CSRFOptions | false
+
+	/** Rate limiter. false to disable. */
+	throttle?: ThrottleOptions | false
+}
+
+/**
+ * Apply middleware to an Elysia app based on config.
+ */
+export function applyMiddleware(app: Elysia, config?: MiddlewareConfig): void {
+	if (!config) return
+
+	// Order matters: CORS → Logger → CSRF → Rate Limit
+
+	if (config.cors !== false) {
+		app.use(corsMiddleware(config.cors ?? {}))
+	}
+
+	if (config.logger !== false) {
+		app.use(loggerMiddleware(config.logger ?? {}))
+	}
+
+	if (config.csrf !== false) {
+		app.use(csrfMiddleware(config.csrf ?? {}))
+	}
+
+	if (config.throttle !== false) {
+		app.use(rateLimiter(config.throttle ?? {}))
+	}
+}

package/dist/helpers/modules.ts

@@ -0,0 +1,115 @@
+/**
+ * HMVC Module System — load modules from `modules/` directory.
+ *
+ * Each module has its own routes/ and views/:
+ * ```
+ * modules/
+ *   blog/
+ *     routes/posts.ts   → GET /blog/posts
+ *     views/posts.html
+ *     config/app.ts     (optional, module-level config)
+ *   shop/
+ *     routes/products.ts → GET /shop/products
+ *     views/products.html
+ * ```
+ *
+ * Cross-module calls:
+ * ```ts
+ * import { moduleRun } from '../helpers/modules'
+ * const posts = await moduleRun('blog/posts', ctx)
+ * ```
+ */
+import { readdirSync, existsSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { Elysia } from 'elysia'
+import { registerFileRoutes } from '../router/file-router'
+import { registerServerRoutes } from '../router/server-router'
+import type { DbClient } from '../db/drizzle'
+import type { Cache } from '../helpers/cache'
+import type { Queue } from '../helpers/queue'
+import type { Upload } from '../helpers/upload'
+import type { Mail } from '../helpers/mail'
+
+export interface ModuleServices {
+	db?: DbClient
+	dbs?: Record<string, DbClient>
+	cache?: Cache
+	queue?: Queue
+	upload?: Upload
+	mail?: Mail
+}
+
+/** Scan and register all modules in the `modules/` directory. */
+export async function registerModules(app: Elysia, services: ModuleServices): Promise<void> {
+	// Compute modules directory relative to CWD
+	const modulesDir = 'modules'
+	if (!existsSync(modulesDir)) return
+
+	const entries = readdirSync(modulesDir, { withFileTypes: true })
+
+	for (const entry of entries) {
+		if (!entry.isDirectory() || entry.name.startsWith('_')) continue
+
+		const moduleName = entry.name
+		const routesDir = join(modulesDir, moduleName, 'routes')
+		const viewsDir = join(modulesDir, moduleName, 'views')
+
+		if (!existsSync(routesDir)) continue
+
+		// Each module registers its routes with its name as prefix
+		await registerFileRoutes(app, {
+			directory: routesDir,
+			viewsDir,
+			prefix: `/${moduleName}`,
+			...services,
+		})
+
+		console.log(`[module] ${moduleName} → /${moduleName}/*`)
+	}
+}
+
+/**
+ * Call a module's controller method programmatically.
+ * Syntax: `moduleRun('blog/posts/index', ctx)` or `moduleRun('blog/posts', ctx)`
+ */
+export async function moduleRun(path: string, ctx?: any): Promise<any> {
+	const parts = path.split('/')
+	const moduleName = parts[0]
+	const method = parts.length > 2 ? parts.pop() : 'index'
+	const controllerPath = parts.slice(1).join('/') || 'index'
+
+	const fullPath = join(process.cwd(), 'modules', moduleName, 'routes', `${controllerPath}.ts`)
+	if (!existsSync(fullPath)) {
+		throw new Error(`[hmvc] Module route not found: ${moduleName}/${controllerPath}`)
+	}
+
+	const mod = await import(fullPath)
+	const ControllerClass = findExport(mod)
+	if (!ControllerClass) throw new Error(`[hmvc] No controller in ${moduleName}/${controllerPath}`)
+
+	const instance = new ControllerClass()
+	if (ctx) {
+		;(instance as any).ctx = ctx
+		if (ctx.session) (instance as any).session = ctx.session
+		if (ctx.db) (instance as any).db = ctx.db
+	}
+
+	const fn = instance[method]
+	if (typeof fn !== 'function') throw new Error(`[hmvc] No method ${method} in ${moduleName}/${controllerPath}`)
+
+	return fn.call(instance)
+}
+
+function findExport(mod: Record<string, any>): any {
+	for (const key of Object.keys(mod)) {
+		const val = mod[key]
+		if (typeof val === 'function' && val.prototype) {
+			let proto = val.prototype
+			while (proto) {
+				if (proto.constructor?.name === 'Controller') return val
+				proto = Object.getPrototypeOf(proto)
+			}
+		}
+	}
+	return null
+}

package/dist/helpers/openapi.ts

@@ -0,0 +1,140 @@
+/**
+ * OpenAPI — auto-generate OpenAPI 3.1 spec from registered routes.
+ *
+ * Users can customize route documentation:
+ *
+ * ```ts
+ * // In any controller file (top-level)
+ * OpenAPIRegistry.add('/posts', 'GET', {
+ *   summary: 'List all posts',
+ *   description: 'Returns paginated list of blog posts',
+ *   tags: ['Blog'],
+ * })
+ * ```
+ */
+import type { Elysia } from 'elysia'
+
+export interface OpenAPIConfig {
+	title?: string
+	version?: string
+	description?: string
+	specPath?: string
+	docsPath?: string
+}
+
+interface RouteDoc {
+	summary?: string
+	description?: string
+	tags?: string[]
+	parameters?: any[]
+	requestBody?: any
+	responses?: Record<string, any>
+	deprecated?: boolean
+}
+
+const defaults: OpenAPIConfig = {
+	title: 'Bunigniter API',
+	version: '1.0.0',
+	specPath: '/openapi.json',
+	docsPath: '/docs',
+}
+
+// ─── User-facing registry ──────────────────────────────────────
+
+const routeDocs = new Map<string, Map<string, RouteDoc>>()
+
+/**
+ * Register OpenAPI documentation for a route.
+ * Call this at the top level of any route file.
+ *
+ * @example
+ * ```ts
+ * // routes/posts.ts
+ * import { OpenAPIRegistry } from 'bunigniter/helpers/openapi'
+ *
+ * OpenAPIRegistry.add('/posts', 'GET', {
+ *   summary: 'List all posts',
+ *   tags: ['Blog'],
+ * })
+ * ```
+ */
+export const OpenAPIRegistry = {
+	add(path: string, method: string, doc: RouteDoc): void {
+		const m = method.toUpperCase()
+		if (!routeDocs.has(path)) routeDocs.set(path, new Map())
+		routeDocs.get(path)!.set(m, doc)
+	},
+}
+
+// ─── Spec generation ───────────────────────────────────────────
+
+export function openapi(app: any, config?: OpenAPIConfig): void {
+	const cfg = { ...defaults, ...config }
+
+	app.get(cfg.specPath, () => {
+		const spec = generateSpec(app, cfg)
+		return new Response(JSON.stringify(spec, null, 2), {
+			headers: { 'content-type': 'application/json' },
+		})
+	})
+
+	app.get(cfg.docsPath, () => {
+		const html = `<!DOCTYPE html>
+<html><head>
+  <title>${cfg.title}</title>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+</head><body>
+  <script id="api-reference" data-url="${cfg.specPath}"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body></html>`
+		return new Response(html, {
+			headers: { 'content-type': 'text/html; charset=utf-8' },
+		})
+	})
+}
+
+function generateSpec(app: any, cfg: OpenAPIConfig): Record<string, any> {
+	const routes: Array<{ method: string; path: string }> = app.routes ?? []
+	const tags = new Set<string>()
+	const paths: Record<string, any> = {}
+
+	for (const route of routes) {
+		const method = route.method.toLowerCase()
+		const path = route.path
+		const userDoc = routeDocs.get(route.path)?.get(route.method)
+
+		if (!paths[path]) paths[path] = {}
+
+		const entry = userDoc ?? {}
+		if (entry.tags) entry.tags.forEach((t: string) => tags.add(t))
+
+		paths[path][method] = {
+			summary: entry.summary ?? `${route.method} ${path}`,
+			description: entry.description ?? '',
+			tags: entry.tags,
+			deprecated: entry.deprecated,
+			parameters: entry.parameters ?? extractParams(path),
+			...(entry.requestBody ? { requestBody: entry.requestBody } : {}),
+			responses: entry.responses ?? { '200': { description: 'Successful response' } },
+		}
+	}
+
+	return {
+		openapi: '3.1.0',
+		info: { title: cfg.title, version: cfg.version, description: cfg.description ?? '' },
+		tags: [...tags].map(name => ({ name })),
+		paths,
+	}
+}
+
+function extractParams(path: string): any[] {
+	const params: any[] = []
+	const matches = path.match(/:(\w+)/g)
+	if (matches) {
+		for (const m of matches) {
+			params.push({ name: m.slice(1), in: 'path', required: true, schema: { type: 'string' } })
+		}
+	}
+	return params
+}