npm - spooder - Versions diffs - 5.0.1 → 5.0.3 - Mend

spooder 5.0.1 → 5.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -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>): 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;
 		});
@@ -1341,6 +1343,172 @@ server.bootstrap({
 });
 ```
+#### Bootstrap Options
+The `BootstrapOptions` object accepts the following properties:
+##### `base?: string | BunFile`
+Optional base template that wraps all route content. The base template should include `{{content}}` where the route content will be inserted.
+```ts
+// Base template: base.html
+<html>
+<head><title>{{title}}</title></head>
+<body>{{content}}</body>
+</html>
+// Usage
+server.bootstrap({
+	base: Bun.file('./templates/base.html'),
+	routes: {
+		'/': {
+			content: '<h1>Welcome</h1>',
+			subs: { title: 'Home' }
+		}
+	}
+});
+```
+##### `routes: Record<string, BootstrapRoute>`
+**Required.** Defines the routes and their content. Each route can have:
+- `content`: The page content (string or BunFile)
+- `subs?`: Template substitutions specific to this route
+```ts
+routes: {
+	'/about': {
+		content: Bun.file('./pages/about.html'),
+		subs: {
+			title: 'About Us',
+			description: 'Learn more about our company'
+		}
+	}
+}
+```
+##### `cache?: CacheOptions | ReturnType<typeof cache_http>`
+Optional HTTP caching configuration. Can be:
+- A `CacheOptions` object (creates new cache instance)
+- An existing cache instance from `cache_http()`
+- Omitted to disable caching
+```ts
+cache: {
+	ttl: 5 * 60 * 1000,     // 5 minutes
+	max_size: 10 * 1024 * 1024, // 10 MB
+	use_etags: true,
+	use_canary_reporting: true
+}
+```
+##### `cache_bust?: boolean`
+When enabled, automatically generates git hash-based cache busting for static assets using dynamic template resolvers.
+```ts
+cache_bust: true
+```
+With `cache_bust` enabled, you can use the `{{asset=filename}}` template function to generate cache-busted URLs:
+**Usage:**
+```ts
+cache_bust: true
+// Creates dynamic asset resolver: {{asset=static/css/style.css}} -> "static/css/style.css?v=a1b2c3d"
+```
+**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)
+- `use_canary_reporting?`: Whether to report errors via canary
+Error templates receive `{{error_code}}` and `{{error_text}}` substitutions.
+```ts
+error: {
+	error_page: Bun.file('./templates/error.html'),
+	use_canary_reporting: true
+}
+```
+##### `static?: object`
+Optional static file serving configuration:
+- `route`: URL path prefix for static files
+- `directory`: Local directory containing static files
+- `sub_ext?`: Array of file extensions that should have template substitution applied
+```ts
+static: {
+	route: '/assets',
+	directory: './public',
+	sub_ext: ['.css', '.js']  // These files get template processing
+}
+```
+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`.
+```ts
+global_subs: {
+	site_name: 'My Website',
+	version: '1.0.0',
+	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
+2. If `base` is defined, content is wrapped using `{{content}}` substitution
+3. Route-specific `subs` and `global_subs` are applied
+4. Hash substitutions (if enabled) are applied
 <a id="api-error-handling"></a>
 ## API > Error Handling
@@ -1692,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
@@ -1803,53 +2002,10 @@ await parse_template(..., {
 </t-for>
 ```
-### 🔧 `generate_hash_subs(length: number, prefix: string, hashes?: Record<string, 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);
-});
-```
 ### 🔧 ``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.
@@ -1859,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 CHANGED Viewed

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

package/src/api.ts CHANGED Viewed

@@ -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,17 +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>): 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))
-		hash_map[prefix + file] = hash;
-	return hash_map;
-}
 // endregion
 // region serving
@@ -976,7 +997,7 @@ type WebsocketHandlers = {
 	drain?: (ws: WebSocket) => void
 };
-type BootstrapSub = string | string[];
+type BootstrapSub = ReplacementValue;
 type BootstrapRoute = {
 	content: string | BunFile;
@@ -1407,8 +1428,20 @@ export function http_serve(port: number, hostname?: string) {
 		/* Bootstrap a static web server */
 		bootstrap: async function(options: BootstrapOptions) {
-			const hash_sub_table = options.cache_bust ? await generate_hash_subs() : {};
-			const global_sub_table = sub_table_merge(hash_sub_table, options.global_subs);
+			let git_hash_table: Record<string, string> = {};
+			let cache_bust_subs = {};
+			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(cache_bust_subs, options.global_subs);
 			let cache = options.cache;
 			if (cache !== undefined && !is_cache_http(cache))