spooder 5.0.2 → 5.0.3

package/README.md

@@ -525,8 +525,8 @@ pipe.once(event: string, callback: (data: object) => void | Promise<void>): void
 pipe.off(event: string): void;
 
 // templates
-parse_template(template: string, replacements: Record<string, string>, drop_missing?: boolean): Promise<string>;
-generate_hash_subs(length?: number, prefix?: string, hashes?: Record<string, string>, format?: string): Promise<Record<string, string>>;
+Replacements = Record<string, string | Array<string> | object | object[]> | ReplacerFn | AsyncReplaceFn;
+parse_template(template: string, replacements: Replacements, drop_missing?: boolean): Promise<string>;
 get_git_hashes(length: number): Promise<Record<string, string>>;
 
 // database interface
@@ -1197,7 +1197,7 @@ server.websocket('/path/to/websocket', {
 For simpler projects, the scaffolding can often look the same, potentially something similar to below.
 
 ```ts
-import { http_serve, cache_http, generate_hash_subs, parse_template, http_apply_range } from 'spooder';
+import { http_serve, cache_http, parse_template, http_apply_range, get_git_hashes } from 'spooder';
 import path from 'node:path';
 
 const server = http_serve(80);
@@ -1209,7 +1209,7 @@ const cache = cache_http({
 });
 
 const base_file = await Bun.file('./html/base_template.html').text();
-const hash_table = await generate_hash_subs();
+const git_hash_table = await get_git_hashes();
 
 async function default_handler(status_code: number): Promise<Response> {
 	const error_text = HTTP_STATUS_CODE[status_code] as string;
@@ -1239,10 +1239,12 @@ server.dir('/static', './static', async (file_path, file, stat, request) => {
 	if (stat.isDirectory())
 		return HTTP_STATUS_CODE.Unauthorized_401;
 
-	// cache busting
+	// serve css/js files directly
 	const ext = path.extname(file_path);
 	if (ext === '.css' || ext === '.js') {
-		const content = await parse_template(await file.text(), hash_table, true);
+		const content = await parse_template(await file.text(), {
+			asset: (file) => git_hash_table[file]
+		}, true);
 
 		return new Response(content, {
 			headers: {
@@ -1261,8 +1263,8 @@ function add_route(route: string, file: string, title: string) {
 			const template = await parse_template(base_file, {
 				title: title,
 				content: file_content,
-				...hash_table	
-			}, false);
+				asset: (file) => git_hash_table[file]
+			}, true);
 
 			return template;
 		});
@@ -1300,7 +1302,7 @@ server.bootstrap({
 		error_page: Bun.file('./html/error.html')
 	},
 	
-	hash_subs: true,
+	cache_bust: true,
 
 	static: {
 		directory: './static',
@@ -1399,37 +1401,30 @@ cache: {
 }
 ```
 
-##### `hash_subs?: boolean | object`
-When enabled, automatically generates git hash-based substitutions. Can be a boolean for defaults or an object for custom options.
+##### `cache_bust?: boolean`
+When enabled, automatically generates git hash-based cache busting for static assets using dynamic template resolvers.
 
-**Boolean usage (uses defaults):**
 ```ts
-hash_subs: true  // Equivalent to { length: 7, prefix: 'hash=' }
+cache_bust: true
 ```
 
-**Object usage (custom options):**
-```ts
-hash_subs: {
-	length: 7,           // Hash length (default: 7)
-	prefix: 'asset=',    // Substitution prefix (default: 'hash=')
-	format: '$file?v=$hash',  // Custom format (default: just hash)
-	hashes: { ... }      // Pre-generated hash map from get_git_hashes (optional)
-}
-```
+With `cache_bust` enabled, you can use the `{{asset=filename}}` template function to generate cache-busted URLs:
 
-**Examples:**
+**Usage:**
 ```ts
-// Default hash substitutions
-hash_subs: true
-// Creates: {{hash=static/css/style.css}} -> "a1b2c3d"
-// Usage: <link href="/css/style.css?v={{hash=static/css/style.css}}">
+cache_bust: true
+// Creates dynamic asset resolver: {{asset=static/css/style.css}} -> "static/css/style.css?v=a1b2c3d"
+```
 
-// Asset-style substitutions (reduces verbosity)
-hash_subs: { prefix: 'asset=', format: '$file?v=$hash' }
-// Creates: {{asset=static/css/style.css}} -> "static/css/style.css?v=a1b2c3d" 
-// Usage: <link href="{{asset=static/css/style.css}}">
+**Template usage:**
+```html
+<link href="{{asset=static/css/style.css}}">
+<script src="{{asset=static/js/app.js}}"></script>
+<img src="{{asset=static/images/logo.png}}">
 ```
 
+The `asset` function automatically appends the git hash as a query parameter for cache busting, or returns the original filename if no hash is available.
+
 ##### `error?: object`
 Optional error page configuration:
 - `error_page`: Template for error pages (string or BunFile)
@@ -1458,7 +1453,25 @@ static: {
 }
 ```
 
-Files with extensions in `sub_ext` will have template substitutions applied before serving.
+Files with extensions in `sub_ext` will have template substitutions applied before serving. This includes support for functions to generate dynamic content:
+
+```ts
+// Dynamic CSS with function-based substitutions
+static: {
+	route: '/assets',
+	directory: './public',
+	sub_ext: ['.css']
+},
+
+global_subs: {
+	theme_color: () => {
+		const hour = new Date().getHours();
+		return hour < 6 || hour > 18 ? '#2d3748' : '#4a5568';
+	}
+}
+```
+
+This allows CSS files to use dynamic substitutions: `color: {{theme_color}};`
 
 ##### `global_subs?: Record<string, BootstrapSub>`
 Optional global template substitutions available to all routes, error pages, and static files with `sub_ext`.
@@ -1467,10 +1480,28 @@ Optional global template substitutions available to all routes, error pages, and
 global_subs: {
 	site_name: 'My Website',
 	version: '1.0.0',
-	api_url: 'https://api.example.com'
+	api_url: 'https://api.example.com',
+	
+	// Function-based substitutions for dynamic content
+	current_year: () => new Date().getFullYear().toString(),
+	
+	build_time: async () => {
+		// Example: fetch build timestamp from git
+		const process = Bun.spawn(['git', 'log', '-1', '--format=%ct']);
+		const output = await Bun.readableStreamToText(process.stdout);
+		return new Date(parseInt(output.trim()) * 1000).toISOString();
+	},
+	
+	user_count: async () => {
+		// Example: dynamic user count from database
+		const count = await db.count('SELECT COUNT(*) as count FROM users');
+		return count.toLocaleString();
+	}
 }
 ```
 
+Functions in `global_subs` and route-specific `subs` are called during template processing, allowing for dynamic content generation. Both synchronous and asynchronous functions are supported.
+
 #### Template Processing Order
 
 1. Route content is loaded
@@ -1829,29 +1860,60 @@ await parse_template(template, replacements, true);
 </html>
 ```
 
-`parse_template` supports passing a function instead of a replacement object. This function will be called for each placeholder and the return value will be used as the replacement. This function can be a Promise/async function.
+#### Custom Replacer Function
+
+`parse_template` supports passing a function instead of a replacement object. This function will be called for each placeholder and the return value will be used as the replacement. Both synchronous and asynchronous functions are supported.
 
 ```ts
-const replacer = (placeholder: string) => {
-	return placeholder.toUpperCase();
+const replacer = (key: string) => {
+	switch (key) {
+		case 'timestamp': return Date.now().toString();
+		case 'random': return Math.random().toString(36).substring(7);
+		case 'greeting': return 'Hello, World!';
+		default: return undefined;
+	}
 };
 
-await parse_template('Hello {{world}}', replacer);
+await parse_template('Generated at {{timestamp}}: {{greeting}} (ID: {{random}})', replacer);
+// Result: "Generated at 1635789123456: Hello, World! (ID: x7k2p9m)"
 ```
 
-```html
-<html>
-	<head>
-		<title>TITLE</title>
-	</head>
-	<body>
-		<h1>TITLE</h1>
-		<p>CONTENT</p>
-		<p>IGNORED</p>
-	</body>
-</html>
+Custom replacer functions are supported on a per-key basis, mixing with static string replacement.
+
+```ts
+await parse_template('Hello {{foo}}, it is {{now}}', {
+	foo: 'world',
+	now: () => Date.now()
+});
+```
+
+#### Key/Value Based Substitutions
+
+`parse_template` supports key/value based substitutions using the `{{key=value}}` syntax. When a function replacer is provided for the key, the value is passed as a parameter to the function.
+
+```ts
+await parse_template('Color: {{hex=blue}}', {
+	hex: (color) => {
+		const colors = { blue: '#0000ff', red: '#ff0000', green: '#00ff00' };
+		return colors[color] || color;
+	}
+});
+// Result: "Color: #0000ff"
+```
+
+Global replacer functions also support the value parameter:
+
+```ts
+await parse_template('Transform: {{upper=hello}} and {{lower=WORLD}}', (key, value) => {
+	if (key === 'upper' && value) return value.toUpperCase();
+	if (key === 'lower' && value) return value.toLowerCase();
+	return 'unknown';
+});
+// Result: "Transform: HELLO and world"
 ```
 
+#### Conditional Rendering
+
 `parse_template` supports conditional rendering with the following syntax.
 
 ```html
@@ -1940,72 +2002,10 @@ await parse_template(..., {
 </t-for>
 ```
 
-### 🔧 `generate_hash_subs(length: number, prefix: string, hashes?: Record<string, string>, format?: string): Promise<Record<string, string>>`
-
-Generate a replacement table for mapping file paths to hashes in templates. This is useful for cache-busting static assets.
-
-> [!IMPORTANT]
-> Internally `generate_hash_subs()` uses `git ls-tree -r HEAD`, so the working directory must be a git repository.
-
-```ts
-let hash_sub_table = {};
-
-generate_hash_subs().then(subs => hash_sub_table = subs).catch(caution);
-
-server.route('/test', (req, url) => {
-	return parse_template('Hello world {{hash=docs/project-logo.png}}', hash_sub_table);
-});
-```
-
-```html
-Hello world 754d9ea
-```
-
-> [!IMPORTANT]
-> Specify paths as they appear in git, relative to the repository root and with forward slashes (no leading slash).
-
-By default hashes are truncated to `7` characters (a short hash), a custom length can be provided instead.
-
-```ts
-generate_hash_subs(40).then(...);
-// d65c52a41a75db43e184d2268c6ea9f9741de63e
-```
-
-> [!NOTE]
-> SHA-1 hashes are `40` characters. Git is transitioning to SHA-256, which are `64` characters. Short hashes of `7` are generally sufficient for cache-busting.
-
-Use a different prefix other than `hash=` by passing it as the first parameter.
-
-```ts
-generate_hash_subs(7, '$#').then(subs => hash_sub_table = subs).catch(caution);
-
-server.route('/test', (req, url) => {
-	return parse_template('Hello world {{$#docs/project-logo.png}}', hash_sub_table);
-});
-```
-
-#### Custom Format Parameter
-
-The optional `format` parameter allows you to customize how the substitution values are formatted. Use `$file` and `$hash` placeholders within the format string:
-
-```ts
-// Asset-style substitutions - reduces verbosity
-const asset_subs = await generate_hash_subs(7, 'asset=', undefined, '$file?v=$hash');
-
-// Usage in templates:
-// <link rel="stylesheet" href="{{asset=static/css/shared.css}}">
-// Resolves to: static/css/shared.css?v=a1b2c3d
-
-// Custom format example:
-await generate_hash_subs(7, 'url=', undefined, 'https://assets.example.com/$file?hash=$hash');
-// Result: { 'url=app.js': 'https://assets.example.com/app.js?hash=a1b2c3d' }
-```
-
-When `format` is omitted, the default behavior returns just the hash value (backward compatible).
 
 ### 🔧 ``get_git_hashes(length: number): Promise<Record<string, string>>``
 
-Internally, `generate_hash_subs()` uses `get_git_hashes()` to retrieve the hash table from git. This function is exposed for convenience.
+Retrieve git hashes for all files in the repository. This is useful for implementing cache-busting functionality or creating file integrity checks.
 
 > [!IMPORTANT]
 > Internally `get_git_hashes()` uses `git ls-tree -r HEAD`, so the working directory must be a git repository.
@@ -2015,14 +2015,11 @@ const hashes = await get_git_hashes(7);
 // { 'docs/project-logo.png': '754d9ea' }
 ```
 
-If you're using `generate_hash_subs()` and `get_git_hashes()` at the same time, it is more efficient to pass the result of `get_git_hashes()` directly to `generate_hash_subs()` to prevent redundant calls to git.
+You can specify the hash length (default is 7 characters for short hashes):
 
 ```ts
-const hashes = await get_git_hashes(7);
-const subs = await generate_hash_subs(7, undefined, hashes);
-
-// hashes[0] -> { 'docs/project-logo.png': '754d9ea' }
-// subs[0] -> { 'hash=docs/project-logo.png': '754d9ea' }
+const full_hashes = await get_git_hashes(40);
+// { 'docs/project-logo.png': 'd65c52a41a75db43e184d2268c6ea9f9741de63e' }
 ```
 
 <a id="api-database"></a>

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "spooder",
 	"type": "module",
-	"version": "5.0.2",
+	"version": "5.0.3",
 	"module": "./src/api.ts",
 	"bin": {
 		"spooder": "./src/cli.ts"

package/src/api.ts

@@ -397,9 +397,14 @@ export async function safe(target_fn: Callable) {
 // endregion
 
 // region templates
-type ReplacerFn = (key: string) => string | Array<string> | undefined;
-type AsyncReplaceFn = (key: string) => Promise<string | Array<string> | undefined>;
-type Replacements = Record<string, string | Array<string> | object | object[]> | ReplacerFn | AsyncReplaceFn;
+type ReplacerFn = (key: string, value?: string) => string | Array<string> | undefined;
+type AsyncReplaceFn = (key: string, value?: string) => Promise<string | Array<string> | undefined>;
+type ReplacementValueFn = () => string | Array<string> | undefined;
+type AsyncReplacementValueFn = () => Promise<string | Array<string> | undefined>;
+type ReplacementValueWithKeyFn = (value?: string) => string | Array<string> | undefined;
+type AsyncReplacementValueWithKeyFn = (value?: string) => Promise<string | Array<string> | undefined>;
+type ReplacementValue = string | Array<string> | object | object[] | ReplacementValueFn | AsyncReplacementValueFn | ReplacementValueWithKeyFn | AsyncReplacementValueWithKeyFn;
+type Replacements = Record<string, ReplacementValue> | ReplacerFn | AsyncReplaceFn;
 
 function get_nested_property(obj: any, path: string): any {
 	const keys = path.split('.');
@@ -435,11 +440,14 @@ export async function parse_template(template: string, replacements: Replacement
 					
 					if (typeof replacements === 'function') {
 						scoped_replacements = async (key: string) => {
-							if (key === alias_name) return loop_entry;
+							if (key === alias_name)
+								return loop_entry;
+
 							if (key.startsWith(alias_name + '.')) {
 								const prop_path = key.substring(alias_name.length + 1);
 								return get_nested_property(loop_entry, prop_path);
 							}
+
 							return await replacements(key);
 						};
 					} else {
@@ -467,6 +475,7 @@ export async function parse_template(template: string, replacements: Replacement
 			
 			if (!drop_missing && !condition_value)
 				return match;
+			
 			if (condition_value)
 				return await parse_template(if_content, replacements, drop_missing);
 			
@@ -478,15 +487,31 @@ export async function parse_template(template: string, replacements: Replacement
 		result = await replace_async(result, var_regex, async (match, var_name) => {
 			// Trim whitespace from variable name
 			var_name = var_name.trim();
+			
+			// Check for key=value syntax
+			let key = var_name;
+			let value: string | undefined = undefined;
+			const equals_index = var_name.indexOf('=');
+
+			if (equals_index !== -1) {
+				key = var_name.substring(0, equals_index);
+				value = var_name.substring(equals_index + 1);
+			}
+			
 			let replacement;
 			
 			if (is_replacer_fn) {
-				replacement = await replacements(var_name);
+				replacement = await replacements(key, value);
 			} else {
 				// First try direct key lookup (handles hash keys with dots like "hash=.gitignore")
 				replacement = replacements[var_name];
 				
-				// If direct lookup fails and variable contains dots, try nested property access
+				// If direct lookup fails and we have key=value syntax, try key lookup
+				if (replacement === undefined && value !== undefined) {
+					replacement = replacements[key];
+				}
+				
+				// If still undefined and variable contains dots, try nested property access
 				if (replacement === undefined && var_name.includes('.')) {
 					const dot_index = var_name.indexOf('.');
 					const base_key = var_name.substring(0, dot_index);
@@ -499,6 +524,13 @@ export async function parse_template(template: string, replacements: Replacement
 				}
 			}
 			
+			if (replacement !== undefined && typeof replacement === 'function') {
+				if (value !== undefined && replacement.length > 0)
+					replacement = await replacement(value);
+				else
+					replacement = await replacement();
+			}
+			
 			if (replacement !== undefined)
 				return replacement;
 			
@@ -549,25 +581,6 @@ export async function get_git_hashes(length = 7): Promise<Record<string, string>
 	return hash_map;
 }
 
-export async function generate_hash_subs(length = 7, prefix = 'hash=', hashes?: Record<string, string>, format?: string): Promise<Record<string, string>> {	
-	const hash_map: Record<string, string> = {};
-	
-	if (!hashes)
-		hashes = await get_git_hashes(length);
-	
-	for (const [file, hash] of Object.entries(hashes)) {
-		if (format !== undefined) {
-			const formatted_value = format
-				.replace(/\$file/g, file)
-				.replace(/\$hash/g, hash);
-			hash_map[prefix + file] = formatted_value;
-		} else {
-			hash_map[prefix + file] = hash;
-		}
-	}
-	
-	return hash_map;
-}
 // endregion
 
 // region serving
@@ -984,7 +997,7 @@ type WebsocketHandlers = {
 	drain?: (ws: WebSocket) => void
 };
 
-type BootstrapSub = string | string[];
+type BootstrapSub = ReplacementValue;
 
 type BootstrapRoute = {
 	content: string | BunFile;
@@ -995,12 +1008,7 @@ type BootstrapOptions = {
 	base?: string | BunFile;
 	routes: Record<string, BootstrapRoute>;
 	cache?: ReturnType<typeof cache_http> | CacheOptions;
-	hash_subs?: boolean | {
-		length?: number;
-		prefix?: string;
-		format?: string;
-		hashes?: Record<string, string>;
-	};
+	cache_bust?: boolean;
 	error?: {
 		use_canary_reporting?: boolean;
 		error_page: string | BunFile;
@@ -1420,18 +1428,20 @@ export function http_serve(port: number, hostname?: string) {
 		
 		/* Bootstrap a static web server */
 		bootstrap: async function(options: BootstrapOptions) {
-			let hash_sub_table = {};
+			let git_hash_table: Record<string, string> = {};
+			let cache_bust_subs = {};
 			
-			if (options.hash_subs) {
-				if (options.hash_subs === true) {
-					hash_sub_table = await generate_hash_subs();
-				} else {
-					const { length, prefix, format, hashes } = options.hash_subs;
-					hash_sub_table = await generate_hash_subs(length, prefix, hashes, format);
-				}
+			if (options.cache_bust) {
+				git_hash_table = await get_git_hashes();
+				cache_bust_subs = {
+					asset: (file: string) => {
+						const hash = git_hash_table[file];
+						return hash ? `${file}?v=${hash}` : file;
+					}
+				};
 			}
 			
-			const global_sub_table = sub_table_merge(hash_sub_table, options.global_subs);
+			const global_sub_table = sub_table_merge(cache_bust_subs, options.global_subs);
 
 			let cache = options.cache;
 			if (cache !== undefined && !is_cache_http(cache))