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

spooder 5.0.1 → 5.0.2

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

@@ -526,7 +526,7 @@ 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>>;
+generate_hash_subs(length?: number, prefix?: string, hashes?: Record<string, string>, format?: string): Promise<Record<string, string>>;
 get_git_hashes(length: number): Promise<Record<string, string>>;
 // database interface
@@ -1300,7 +1300,7 @@ server.bootstrap({
 		error_page: Bun.file('./html/error.html')
 	},
-	cache_bust: true,
+	hash_subs: true,
 	static: {
 		directory: './static',
@@ -1341,6 +1341,143 @@ 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
+}
+```
+##### `hash_subs?: boolean | object`
+When enabled, automatically generates git hash-based substitutions. Can be a boolean for defaults or an object for custom options.
+**Boolean usage (uses defaults):**
+```ts
+hash_subs: true  // Equivalent to { length: 7, prefix: 'hash=' }
+```
+**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)
+}
+```
+**Examples:**
+```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}}">
+// 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}}">
+```
+##### `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.
+##### `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'
+}
+```
+#### 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
@@ -1803,7 +1940,7 @@ await parse_template(..., {
 </t-for>
 ```
-### 🔧 `generate_hash_subs(length: number, prefix: string, hashes?: Record<string, string>): Promise<Record<string, string>>`
+### 🔧 `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.
@@ -1847,6 +1984,25 @@ server.route('/test', (req, url) => {
 });
 ```
+#### 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.

package/package.json CHANGED Viewed

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

package/src/api.ts CHANGED Viewed

@@ -549,14 +549,22 @@ 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>> {
+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))
-		hash_map[prefix + file] = hash;
+	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;
 }
@@ -987,7 +995,12 @@ type BootstrapOptions = {
 	base?: string | BunFile;
 	routes: Record<string, BootstrapRoute>;
 	cache?: ReturnType<typeof cache_http> | CacheOptions;
-	cache_bust?: boolean;
+	hash_subs?: boolean | {
+		length?: number;
+		prefix?: string;
+		format?: string;
+		hashes?: Record<string, string>;
+	};
 	error?: {
 		use_canary_reporting?: boolean;
 		error_page: string | BunFile;
@@ -1407,7 +1420,17 @@ 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() : {};
+			let hash_sub_table = {};
+			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);
+				}
+			}
 			const global_sub_table = sub_table_merge(hash_sub_table, options.global_subs);
 			let cache = options.cache;