bunigniter 0.2.0

package/dist/helpers/pagination.ts

@@ -0,0 +1,159 @@
+/**
+ * Pagination — CodeIgniter-style pagination helper.
+ *
+ * Wraps query results with pagination metadata.
+ *
+ * @example
+ * ```ts
+ * const result = await this.db.paginate('SELECT * FROM users', { page: 1, perPage: 20 })
+ * // → { data: User[], total: 100, page: 1, perPage: 20, pages: 5 }
+ * ```
+ */
+export interface PaginateOptions {
+	/** Current page (1-indexed). Default: 1 */
+	page?: number
+
+	/** Items per page. Default: 20 */
+	perPage?: number
+
+	/** Base URL for generated links. */
+	baseUrl?: string
+}
+
+export interface PaginateResult<T = any> {
+	/** Page items. */
+	data: T[]
+
+	/** Total items across all pages. */
+	total: number
+
+	/** Current page number. */
+	page: number
+
+	/** Items per page. */
+	perPage: number
+
+	/** Total pages. */
+	pages: number
+
+	/** Is this the first page? */
+	firstPage: boolean
+
+	/** Is this the last page? */
+	lastPage: boolean
+
+	/** Count of items on current page. */
+	count: number
+
+	/** Previous page number (null if first). */
+	prevPage: number | null
+
+	/** Next page number (null if last). */
+	nextPage: number | null
+
+	/** Generated pagination links (simple HTML). */
+	links: string
+}
+
+/**
+ * Wrap an array with pagination metadata.
+ *
+ * @param data - Items for the current page
+ * @param total - Total items across all pages
+ * @param options - Pagination options
+ *
+ * @example
+ * ```ts
+ * const result = paginate(rows, totalCount, { page: 1, perPage: 20 })
+ * ```
+ */
+export function paginate<T = any>(
+	data: T[],
+	total: number,
+	options: PaginateOptions = {}
+): PaginateResult<T> {
+	const page = Math.max(1, options.page ?? 1)
+	const perPage = Math.max(1, options.perPage ?? 20)
+	const pages = Math.max(1, Math.ceil(total / perPage))
+	const currentPage = Math.min(page, pages)
+
+	return {
+		data,
+		total,
+		page: currentPage,
+		perPage,
+		pages,
+		firstPage: currentPage === 1,
+		lastPage: currentPage === pages,
+		count: data.length,
+		prevPage: currentPage > 1 ? currentPage - 1 : null,
+		nextPage: currentPage < pages ? currentPage + 1 : null,
+		links: generateLinks(total, currentPage, pages, options.baseUrl ?? ''),
+	}
+}
+
+/**
+ * Generate simple HTML pagination links.
+ */
+function generateLinks(total: number, page: number, pages: number, baseUrl: string): string {
+	if (pages <= 1) return ''
+
+	const prev = page > 1 ? `<a href="${baseUrl}?page=${page - 1}">&laquo; Prev</a>` : '<span>&laquo; Prev</span>'
+	const next = page < pages ? `<a href="${baseUrl}?page=${page + 1}">Next &raquo;</a>` : '<span>Next &raquo;</span>'
+
+	let numbers = ''
+	const start = Math.max(1, page - 2)
+	const end = Math.min(pages, page + 2)
+
+	for (let i = start; i <= end; i++) {
+		if (i === page) {
+			numbers += `<strong>${i}</strong> `
+		} else {
+			numbers += `<a href="${baseUrl}?page=${i}">${i}</a> `
+		}
+	}
+
+	return `<div class="pagination">${prev} ${numbers} ${next}</div>`
+}
+
+/**
+ * Add paginate helper to DbClient prototype.
+ * Usage: `this.db.paginate('SELECT * FROM users', [], { page: 1, perPage: 20 })`
+ */
+export function addPaginationToDb(db: any): void {
+	if (!db || db._paginateAdded) return
+	db._paginateAdded = true
+
+	/**
+	 * Execute a paginated query.
+	 *
+	 * @param sql - SQL query (without LIMIT/OFFSET)
+	 * @param params - Query parameters
+	 * @param options - Pagination options
+	 */
+	db.paginate = async function <T = any>(
+		sql: string,
+		params: unknown[] = [],
+		options: PaginateOptions = {}
+	): Promise<PaginateResult<T>> {
+		const page = Math.max(1, options.page ?? 1)
+		const perPage = Math.max(1, options.perPage ?? 20)
+		const offset = (page - 1) * perPage
+
+		// Count total
+		const countSql = `SELECT count(*) as count FROM (${sql}) _count`
+		const countResult = await this.query(countSql, params)
+		const total = Number(countResult.rows[0]?.count ?? 0)
+
+		// Fetch page
+		const pageSql = dialectLimitOffset(sql, perPage, offset)
+		const dataResult = await this.query<T>(pageSql, params)
+
+		return paginate(dataResult.rows, total, { page, perPage })
+	}
+}
+
+/** Add LIMIT/OFFSET for different dialects. */
+function dialectLimitOffset(sql: string, limit: number, offset: number): string {
+	return `${sql} LIMIT ${limit} OFFSET ${offset}`
+}

package/dist/helpers/queue.ts

@@ -0,0 +1,186 @@
+/**
+ * Queue — simple in-memory job queue.
+ *
+ * @example
+ * ```ts
+ * // In a controller
+ * this.queue.dispatch('send_email', { to: 'user@test.com', template: 'welcome' })
+ *
+ * // Process jobs
+ * this.queue.process('send_email', async (job) => {
+ *   await mail.send(job.data)
+ * })
+ * ```
+ */
+export interface QueueOptions {
+	/** Max concurrent workers per queue. Default: 5 */
+	maxConcurrency?: number
+
+	/** Poll interval in ms when idle. Default: 1000 */
+	pollInterval?: number
+}
+
+export interface Job<T = any> {
+	id: string
+	name: string
+	data: T
+	attempts: number
+	maxAttempts: number
+	createdAt: number
+}
+
+type JobHandler<T = any> = (job: Job<T>) => Promise<void>
+
+interface QueueState {
+	pending: Job[]
+	processing: Set<string>
+	handlers: Map<string, JobHandler>
+	running: boolean
+}
+
+/** In-memory queue store. */
+const queues = new Map<string, QueueState>()
+
+/**
+ * Queue service — dispatch and process background jobs.
+ *
+ * Usage in a Controller:
+ * ```ts
+ * this.queue.dispatch('send_email', { to: 'user@test.com' })
+ * ```
+ */
+export class Queue {
+	private options: QueueOptions
+
+	constructor(options: QueueOptions = {}) {
+		this.options = {
+			maxConcurrency: options.maxConcurrency ?? 5,
+			pollInterval: options.pollInterval ?? 1000,
+		}
+	}
+
+	/**
+	 * Dispatch a job to a queue.
+	 *
+	 * @param name - Queue name
+	 * @param data - Job payload
+	 * @param maxAttempts - Max retry attempts. Default: 3
+	 * @returns Job ID
+	 */
+	dispatch(name: string, data: any, maxAttempts = 3): string {
+		const state = getOrCreateQueue(name)
+		const job: Job = {
+			id: crypto.randomUUID(),
+			name,
+			data,
+			attempts: 0,
+			maxAttempts,
+			createdAt: Date.now(),
+		}
+		state.pending.push(job)
+		return job.id
+	}
+
+	/**
+	 * Register a handler for a queue.
+	 * Starts processing when a handler is registered.
+	 */
+	process(name: string, handler: JobHandler): void {
+		const state = getOrCreateQueue(name)
+		state.handlers.set(name, handler)
+		startProcessing(name, state, this.options)
+	}
+
+	/**
+	 * Get queue status.
+	 */
+	status(name: string): { pending: number; processing: number } {
+		const state = queues.get(name)
+		if (!state) return { pending: 0, processing: 0 }
+		return {
+			pending: state.pending.length,
+			processing: state.processing.size,
+		}
+	}
+
+	/**
+	 * Get all queue names.
+	 */
+	get queues(): string[] {
+		return [...queues.keys()]
+	}
+}
+
+function getOrCreateQueue(name: string): QueueState {
+	let state = queues.get(name)
+	if (!state) {
+		state = {
+			pending: [],
+			processing: new Set(),
+			handlers: new Map(),
+			running: false,
+		}
+		queues.set(name, state)
+	}
+	return state
+}
+
+function startProcessing(name: string, state: QueueState, options: QueueOptions): void {
+	if (state.running) return
+	state.running = true
+
+	const processNext = async () => {
+		if (!state.running) return
+
+		// Check concurrency
+		if (state.processing.size >= (options.maxConcurrency ?? 5)) {
+			setTimeout(processNext, options.pollInterval ?? 1000)
+			return
+		}
+
+		const job = state.pending.shift()
+		if (!job) {
+			setTimeout(processNext, options.pollInterval ?? 1000)
+			return
+		}
+
+		const handler = state.handlers.get(name)
+		if (!handler) {
+			// No handler registered — put job back
+			state.pending.unshift(job)
+			setTimeout(processNext, options.pollInterval ?? 1000)
+			return
+		}
+
+		state.processing.add(job.id)
+		try {
+			await handler(job)
+		} catch (err) {
+			job.attempts++
+			if (job.attempts < job.maxAttempts) {
+				// Retry with exponential backoff
+				const delay = Math.min(1000 * Math.pow(2, job.attempts), 30000)
+				setTimeout(() => {
+					state.pending.push(job)
+				}, delay)
+			} else {
+				console.error(`[queue] Job ${job.name}/${job.id} failed after ${job.attempts} attempts:`, err)
+			}
+		} finally {
+			state.processing.delete(job.id)
+		}
+
+		// Process next job immediately
+		setImmediate(processNext)
+	}
+
+	processNext()
+}
+
+let _queueInstance: Queue | null = null
+export function createQueue(options?: QueueOptions): Queue {
+	if (!_queueInstance) {
+		_queueInstance = new Queue(options)
+	}
+	return _queueInstance
+}

package/dist/helpers/request-context.ts

@@ -0,0 +1,13 @@
+/**
+ * Request Context — global holder for current request context.
+ * Used by DbClient to log SQL queries to the debug toolbar.
+ */
+let currentCtx: any = null
+
+export function setRequestContext(ctx: any): void {
+	currentCtx = ctx
+}
+
+export function getRequestContext(): any {
+	return currentCtx
+}