@buenojs/bueno 0.8.4 → 0.8.6

package/src/templates/renderers/simple.ts

@@ -0,0 +1,269 @@
+/**
+ * Simple Template Renderer
+ *
+ * Lightweight renderer for:
+ * - Variable interpolation: {{ variable }}
+ * - Filters: {{ value | uppercase | trim }}
+ * - Conditionals: {{ if condition }} ... {{ endif }}
+ *
+ * No dependencies, ~180 lines
+ */
+
+import type { FilterRegistry, TemplateData } from "../types";
+
+/**
+ * Built-in filters
+ */
+const builtinFilters: FilterRegistry = {
+	uppercase: (value) => String(value).toUpperCase(),
+	lowercase: (value) => String(value).toLowerCase(),
+	capitalize: (value) => {
+		const str = String(value);
+		return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+	},
+	trim: (value) => String(value).trim(),
+	reverse: (value) => String(value).split("").reverse().join(""),
+	length: (value) => {
+		if (Array.isArray(value)) return value.length;
+		if (typeof value === "string") return value.length;
+		return 0;
+	},
+	join: (value, separator = ",") => {
+		if (Array.isArray(value)) return value.join(String(separator));
+		return String(value);
+	},
+	slice: (value, start = 0, end = undefined) => {
+		const str = String(value);
+		return str.slice(Number(start), end ? Number(end) : undefined);
+	},
+	default: (value, defaultVal) => {
+		if (value === null || value === undefined || value === "") {
+			return defaultVal;
+		}
+		return value;
+	},
+	isEmpty: (value) => {
+		if (Array.isArray(value)) return value.length === 0;
+		if (value === null || value === undefined || value === "") return true;
+		return false;
+	},
+	date: (value, format = "YYYY-MM-DD") => {
+		if (!(value instanceof Date)) {
+			value = new Date(value);
+		}
+		if (isNaN(value.getTime())) return String(value);
+
+		const year = value.getFullYear();
+		const month = String(value.getMonth() + 1).padStart(2, "0");
+		const date = String(value.getDate()).padStart(2, "0");
+		const hours = String(value.getHours()).padStart(2, "0");
+		const minutes = String(value.getMinutes()).padStart(2, "0");
+		const seconds = String(value.getSeconds()).padStart(2, "0");
+
+		return (format as string)
+			.replace("YYYY", String(year))
+			.replace("MM", month)
+			.replace("DD", date)
+			.replace("HH", hours)
+			.replace("mm", minutes)
+			.replace("ss", seconds);
+	},
+};
+
+/**
+ * Safely get nested property from object
+ */
+function getNestedValue(obj: unknown, path: string): unknown {
+	const parts = path.split(".");
+	let current = obj;
+
+	for (const part of parts) {
+		if (current === null || current === undefined) {
+			return undefined;
+		}
+		current = (current as Record<string, unknown>)[part];
+	}
+
+	return current;
+}
+
+/**
+ * Evaluate simple conditions
+ * Supports: variable, !variable, var1 && var2, var1 || var2
+ */
+function evaluateCondition(condition: string, data: TemplateData): boolean {
+	condition = condition.trim();
+
+	// Handle logical operators (simple parsing, left-to-right)
+	if (condition.includes("||")) {
+		return condition
+			.split("||")
+			.map((c) => evaluateCondition(c.trim(), data))
+			.some((result) => result);
+	}
+
+	if (condition.includes("&&")) {
+		return condition
+			.split("&&")
+			.map((c) => evaluateCondition(c.trim(), data))
+			.every((result) => result);
+	}
+
+	// Handle negation
+	if (condition.startsWith("!")) {
+		return !evaluateCondition(condition.slice(1).trim(), data);
+	}
+
+	// Get variable value
+	const value = getNestedValue(data, condition);
+
+	// Truthy check
+	return Boolean(value);
+}
+
+/**
+ * Simple template renderer
+ */
+export class SimpleRenderer {
+	private filters: FilterRegistry;
+
+	constructor(customFilters?: FilterRegistry) {
+		this.filters = { ...builtinFilters, ...(customFilters || {}) };
+	}
+
+	/**
+	 * Render template with data
+	 */
+	render(template: string, data: TemplateData): string {
+		let result = template;
+
+		// First, handle conditionals ({{ if ... }} ... {{ endif }})
+		result = this._processConditionals(result, data);
+
+		// Then, handle variables and filters ({{ var | filter1 | filter2 }})
+		result = this._processVariables(result, data);
+
+		return result;
+	}
+
+	/**
+	 * Process conditional blocks
+	 */
+	private _processConditionals(template: string, data: TemplateData): string {
+		// Match: {{ if condition }} ... {{ else }} ... {{ endif }}
+		// Handle else blocks properly
+		let result = template;
+
+		// Process nested if blocks (inside-out)
+		const ifRegex = /\{\{\s*if\s+([^}]+)\s*\}\}([\s\S]*?)\{\{\s*endif\s*\}\}/;
+
+		while (ifRegex.test(result)) {
+			result = result.replace(ifRegex, (match, condition, content) => {
+				// Check for else block
+				const elseRegex = /\{\{\s*else\s*\}\}([\s\S]*)$/;
+				let thenBlock = content;
+				let elseBlock = "";
+
+				const elseMatch = content.match(elseRegex);
+				if (elseMatch) {
+					thenBlock = content.substring(0, elseMatch.index);
+					elseBlock = elseMatch[1];
+				}
+
+				// Evaluate condition
+				if (evaluateCondition(condition, data)) {
+					return thenBlock;
+				} else {
+					return elseBlock;
+				}
+			});
+		}
+
+		return result;
+	}
+
+	/**
+	 * Process variable interpolation and filters
+	 */
+	private _processVariables(template: string, data: TemplateData): string {
+		// Match: {{ var | filter1(arg) | filter2 }}
+		const varRegex = /\{\{\s*([^|}\s][^}]*?)\s*(?:\|([^}]*?))?\s*\}\}/g;
+
+		return template.replace(varRegex, (match, varPath, filterChain) => {
+			// Get variable value
+			let value = getNestedValue(data, varPath.trim());
+
+			// If undefined, return empty string
+			if (value === undefined || value === null) {
+				return "";
+			}
+
+			// Apply filters if present
+			if (filterChain) {
+				const filters = filterChain.split("|").map((f) => f.trim());
+
+				for (const filterStr of filters) {
+					// Parse filter and arguments: "uppercase" or "slice(1, 5)"
+					const filterMatch = filterStr.match(/^(\w+)(?:\(([^)]*)\))?$/);
+					if (!filterMatch) continue;
+
+					const filterName = filterMatch[1];
+					const argsStr = filterMatch[2];
+					const filterFn = this.filters[filterName];
+
+					if (!filterFn) {
+						console.warn(`Unknown filter: ${filterName}`);
+						continue;
+					}
+
+					// Parse arguments (simple string splitting)
+					const args: unknown[] = [];
+					if (argsStr) {
+						// Simple parsing: split by comma, handle quoted strings
+						let current = "";
+						let inQuotes = false;
+						let quoteChar = "";
+						for (const char of argsStr) {
+							if ((char === '"' || char === "'") && !inQuotes) {
+								inQuotes = true;
+								quoteChar = char;
+							} else if (char === quoteChar && inQuotes) {
+								inQuotes = false;
+								quoteChar = "";
+							} else if (char === "," && !inQuotes) {
+								const trimmed = current.trim();
+								// Remove quotes if present
+								const unquoted = trimmed.replace(/^["']|["']$/g, "");
+								args.push(unquoted);
+								current = "";
+							} else {
+								current += char;
+							}
+						}
+						if (current) {
+							const trimmed = current.trim();
+							const unquoted = trimmed.replace(/^["']|["']$/g, "");
+							args.push(unquoted);
+						}
+					}
+
+					// Apply filter
+					value = filterFn(value, ...args);
+				}
+			}
+
+			// Convert to string
+			return String(value);
+		});
+	}
+
+	/**
+	 * Register custom filter
+	 */
+	registerFilter(
+		name: string,
+		fn: (value: unknown, ...args: unknown[]) => unknown,
+	): void {
+		this.filters[name] = fn;
+	}
+}

package/src/templates/types.ts

@@ -0,0 +1,154 @@
+/**
+ * Template System Types
+ *
+ * Core interfaces for the lightweight, multi-purpose template engine.
+ * Supports: Variables, filters, conditionals, Markdown rendering, and channel-specific variants.
+ */
+
+/**
+ * Job status enumeration
+ */
+export type JobStatus =
+	| "pending"
+	| "processing"
+	| "completed"
+	| "failed"
+	| "delayed";
+
+/**
+ * Template metadata from front matter
+ */
+export interface TemplateMetadata {
+	/** Channel variants supported by this template */
+	variants?: string[];
+	/** Default variant if not specified */
+	default?: string;
+	/** Template description */
+	description?: string;
+	/** Custom metadata */
+	[key: string]: unknown;
+}
+
+/**
+ * Parsed template with content and metadata
+ */
+export interface Template {
+	/** Template identifier (path without extension) */
+	id: string;
+	/** Template format: "markdown", "text", or "html" */
+	format: "markdown" | "text" | "html";
+	/** Raw template content */
+	content: string;
+	/** Channel-specific variants: { "email": "...", "sms": "...", "push": "..." } */
+	variants: Record<string, string>;
+	/** Front matter metadata */
+	metadata: TemplateMetadata;
+	/** When template was loaded (for cache invalidation) */
+	loadedAt: number;
+}
+
+/**
+ * Options for rendering a template
+ */
+export interface RenderOptions {
+	/** Specific variant to use (overrides auto-detection) */
+	variant?: string;
+	/** Output format: "html" for email, "text" for SMS/plain text */
+	outputFormat?: "html" | "text";
+	/** Timezone for date filters */
+	timezone?: string;
+	/** Locale for i18n (future) */
+	locale?: string;
+}
+
+/**
+ * Template engine data (variables passed to renderer)
+ */
+export interface TemplateData {
+	[key: string]: unknown;
+}
+
+/**
+ * Renderer interface (implemented by SimpleRenderer, MarkdownRenderer, etc.)
+ */
+export interface IRenderer {
+	/** Render template with data */
+	render(template: string, data: TemplateData): Promise<string>;
+}
+
+/**
+ * Filter function signature
+ */
+export type FilterFn = (value: unknown, ...args: unknown[]) => unknown;
+
+/**
+ * Built-in filters registry
+ */
+export interface FilterRegistry {
+	[filterName: string]: FilterFn;
+}
+
+/**
+ * Template loader options
+ */
+export interface TemplateLoaderOptions {
+	/** Base path to templates directory */
+	basePath: string;
+	/** Enable caching */
+	cacheEnabled?: boolean;
+	/** Cache time-to-live in seconds */
+	cacheTtl?: number;
+	/** Max number of templates in cache */
+	maxCacheSize?: number;
+	/** Watch for file changes in development */
+	watch?: boolean;
+	/** File extension to look for */
+	extension?: string;
+}
+
+/**
+ * Template engine configuration
+ */
+export interface TemplateEngineConfig {
+	/** Base path for templates */
+	basePath: string;
+	/** Cache configuration */
+	cache?: {
+		enabled: boolean;
+		ttl: number;
+		maxSize: number;
+	};
+	/** Watch for changes in development */
+	watch?: boolean;
+	/** Default locale (future i18n) */
+	locale?: string;
+	/** Default output format */
+	defaultFormat?: "html" | "text";
+	/** Channel to variant mapping for auto-detection */
+	channelVariantMap?: Record<string, string>;
+}
+
+/**
+ * Template load event
+ */
+export interface TemplateLoadedEvent {
+	templateId: string;
+	source: "memory" | "disk";
+	duration: number;
+}
+
+/**
+ * Template engine metrics
+ */
+export interface TemplateEngineMetrics {
+	/** Total templates loaded */
+	loaded: number;
+	/** Number of cache hits */
+	cacheHits: number;
+	/** Number of cache misses */
+	cacheMisses: number;
+	/** Average render time in milliseconds */
+	avgRenderTime: number;
+	/** Total renders */
+	totalRenders: number;
+}

package/src/testing/index.ts

@@ -598,7 +598,9 @@ export class TestCache {
 /**
  * Create a new TestCache instance, optionally with initial data
  */
-export async function createTestCache(initialData?: Record<string, unknown>): Promise<TestCache> {
+export async function createTestCache(
+	initialData?: Record<string, unknown>,
+): Promise<TestCache> {
 	const cache = new TestCache();
 	if (initialData) {
 		await cache.setMany(initialData);
@@ -748,7 +750,10 @@ export class TestDatabase {
 	/**
 	 * Execute a SQL query and return results
 	 */
-	async query<T = unknown>(sqlString: string, params: unknown[] = []): Promise<T[]> {
+	async query<T = unknown>(
+		sqlString: string,
+		params: unknown[] = [],
+	): Promise<T[]> {
 		this.ensureConnection();
 
 		this._operations.push({
@@ -768,7 +773,10 @@ export class TestDatabase {
 	/**
 	 * Execute a query and return a single row
 	 */
-	async queryOne<T = unknown>(sqlString: string, params: unknown[] = []): Promise<T | null> {
+	async queryOne<T = unknown>(
+		sqlString: string,
+		params: unknown[] = [],
+	): Promise<T | null> {
 		const results = await this.query<T>(sqlString, params);
 		return results.length > 0 ? results[0] : null;
 	}
@@ -776,7 +784,14 @@ export class TestDatabase {
 	/**
 	 * Execute a statement (INSERT, UPDATE, DELETE)
 	 */
-	async execute(sqlString: string, params: unknown[] = []): Promise<{ rows: unknown[]; rowCount: number; insertId?: number | string }> {
+	async execute(
+		sqlString: string,
+		params: unknown[] = [],
+	): Promise<{
+		rows: unknown[];
+		rowCount: number;
+		insertId?: number | string;
+	}> {
 		this.ensureConnection();
 
 		this._operations.push({
@@ -907,7 +922,10 @@ export class TestDatabase {
 	/**
 	 * Create a table from column definitions
 	 */
-	async createTable(name: string, columns: Record<string, string>): Promise<void> {
+	async createTable(
+		name: string,
+		columns: Record<string, string>,
+	): Promise<void> {
 		const columnDefs = Object.entries(columns)
 			.map(([colName, def]) => `${colName} ${def}`)
 			.join(", ");
@@ -941,14 +959,27 @@ export class TestDatabase {
 	/**
 	 * Get table info
 	 */
-	async getTableInfo(table: string): Promise<{ cid: number; name: string; type: string; notnull: number; dflt_value: unknown; pk: number }[]> {
+	async getTableInfo(table: string): Promise<
+		{
+			cid: number;
+			name: string;
+			type: string;
+			notnull: number;
+			dflt_value: unknown;
+			pk: number;
+		}[]
+	> {
 		return this.query(`PRAGMA table_info(${table})`);
 	}
 
 	/**
 	 * Count rows in a table
 	 */
-	async count(table: string, where?: string, params: unknown[] = []): Promise<number> {
+	async count(
+		table: string,
+		where?: string,
+		params: unknown[] = [],
+	): Promise<number> {
 		const sql = where
 			? `SELECT COUNT(*) as count FROM ${table} WHERE ${where}`
 			: `SELECT COUNT(*) as count FROM ${table}`;
@@ -960,7 +991,11 @@ export class TestDatabase {
 	/**
 	 * Check if a row exists
 	 */
-	async exists(table: string, where: string, params: unknown[] = []): Promise<boolean> {
+	async exists(
+		table: string,
+		where: string,
+		params: unknown[] = [],
+	): Promise<boolean> {
 		const count = await this.count(table, where, params);
 		return count > 0;
 	}
@@ -985,7 +1020,9 @@ export class TestDatabase {
 /**
  * Create a new TestDatabase instance, optionally with schema and seed data
  */
-export async function createTestDatabase(options: TestDatabaseOptions = {}): Promise<TestDatabase> {
+export async function createTestDatabase(
+	options: TestDatabaseOptions = {},
+): Promise<TestDatabase> {
 	const db = new TestDatabase();
 	await db.connect();
 
@@ -1059,7 +1096,10 @@ export async function assertTableNotHasRow(
 /**
  * Assert table exists in database
  */
-export async function assertTableExists(db: TestDatabase, table: string): Promise<void> {
+export async function assertTableExists(
+	db: TestDatabase,
+	table: string,
+): Promise<void> {
 	const tables = await db.getTables();
 	if (!tables.includes(table)) {
 		throw new Error(
@@ -1071,7 +1111,10 @@ export async function assertTableExists(db: TestDatabase, table: string): Promis
 /**
  * Assert table does not exist in database
  */
-export async function assertTableNotExists(db: TestDatabase, table: string): Promise<void> {
+export async function assertTableNotExists(
+	db: TestDatabase,
+	table: string,
+): Promise<void> {
 	const tables = await db.getTables();
 	if (tables.includes(table)) {
 		throw new Error(`Expected table "${table}" to NOT exist`);
@@ -1106,15 +1149,32 @@ export async function assertTableValue<T = unknown>(
 }
 // ============= Test Storage =============
 
-import { mkdir, rm, readdir, stat as fsStat, copyFile, rename, unlink } from "node:fs/promises";
-import { join, resolve, relative } from "node:path";
+import {
+	copyFile,
+	stat as fsStat,
+	mkdir,
+	readdir,
+	rename,
+	rm,
+	unlink,
+} from "node:fs/promises";
 import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
 
 /**
  * Storage operation record for testing
  */
 export interface StorageOperation {
-	type: "write" | "read" | "delete" | "exists" | "list" | "stat" | "copy" | "move" | "clear";
+	type:
+		| "write"
+		| "read"
+		| "delete"
+		| "exists"
+		| "list"
+		| "stat"
+		| "copy"
+		| "move"
+		| "clear";
 	path?: string;
 	src?: string;
 	dest?: string;
@@ -1179,10 +1239,13 @@ export class TestStorage {
 	 * @param path - Relative path within storage
 	 * @param content - String or binary content
 	 */
-	async write(path: string, content: string | Uint8Array | ArrayBuffer): Promise<void> {
+	async write(
+		path: string,
+		content: string | Uint8Array | ArrayBuffer,
+	): Promise<void> {
 		await this.ensureInitialized();
 		const fullPath = this.resolvePath(path);
-		
+
 		// Ensure parent directory exists
 		const parentDir = fullPath.substring(0, fullPath.lastIndexOf("/"));
 		if (parentDir) {
@@ -1192,7 +1255,7 @@ export class TestStorage {
 		// Write content using Bun.file()
 		const file = Bun.file(fullPath);
 		const writer = file.writer();
-		
+
 		if (typeof content === "string") {
 			writer.write(content);
 		} else if (content instanceof Uint8Array) {
@@ -1200,12 +1263,13 @@ export class TestStorage {
 		} else if (content instanceof ArrayBuffer) {
 			writer.write(new Uint8Array(content));
 		}
-		
+
 		await writer.end();
 
-		const size = typeof content === "string" 
-			? new TextEncoder().encode(content).length 
-			: content.byteLength;
+		const size =
+			typeof content === "string"
+				? new TextEncoder().encode(content).length
+				: content.byteLength;
 
 		this._operations.push({
 			type: "write",
@@ -1437,7 +1501,7 @@ export class TestStorage {
 	 */
 	async clear(): Promise<void> {
 		await this.ensureInitialized();
-		
+
 		try {
 			const files = await this.list();
 			for (const file of files) {
@@ -1505,8 +1569,11 @@ export class TestStorage {
  * Create a new TestStorage instance
  * @param options - Optional configuration
  */
-export async function createTestStorage(options: TestStorageOptions = {}): Promise<TestStorage> {
-	const basePath = options.basePath ?? await createTempDir("bueno-test-storage-");
+export async function createTestStorage(
+	options: TestStorageOptions = {},
+): Promise<TestStorage> {
+	const basePath =
+		options.basePath ?? (await createTempDir("bueno-test-storage-"));
 	const storage = new TestStorage(basePath);
 	await storage.init();
 	return storage;
@@ -1527,7 +1594,10 @@ async function createTempDir(prefix: string): Promise<string> {
 /**
  * Assert that a file exists in storage
  */
-export async function assertFileExists(storage: TestStorage, path: string): Promise<void> {
+export async function assertFileExists(
+	storage: TestStorage,
+	path: string,
+): Promise<void> {
 	const exists = await storage.exists(path);
 	if (!exists) {
 		const files = await storage.list();
@@ -1540,7 +1610,10 @@ export async function assertFileExists(storage: TestStorage, path: string): Prom
 /**
  * Assert that a file does not exist in storage
  */
-export async function assertFileNotExists(storage: TestStorage, path: string): Promise<void> {
+export async function assertFileNotExists(
+	storage: TestStorage,
+	path: string,
+): Promise<void> {
 	const exists = await storage.exists(path);
 	if (exists) {
 		throw new Error(`Expected file "${path}" to NOT exist`);
@@ -1583,4 +1656,4 @@ export async function assertFileSize(
 			`Expected file "${path}" to have size ${expectedSize}, got ${stats.size}`,
 		);
 	}
-}
+}