spooder 5.0.3 → 5.1.0

package/README.md

@@ -96,6 +96,8 @@ The `CLI` component of `spooder` is a global command-line tool for running serve
 - [API > Workers](#api-workers)
 - [API > Caching](#api-caching)
 - [API > Templating](#api-templating)
+- [API > Cache Busting](#api-cache-busting)
+- [API > Git](#api-git)
 - [API > Database](#api-database)
 	- [API > Database > Schema](#api-database-schema)
 	- [API > Database > Interface](#api-database-interface)
@@ -527,7 +529,16 @@ pipe.off(event: string): void;
 // templates
 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>>;
+
+// cache busting
+cache_bust(string: path, format: string): string
+cache_bust_set_hash_length(length: number): void;
+cache_bust_set_format(format: string): void;
+cache_bust_get_hash_table(): Record<string, string>;
+
+// git
+git_get_hashes(length: number): Promise<Record<string, string>>;
+git_get_hashes_sync(length: number): Record<string, string>
 
 // database interface
 db_sqlite(filename: string, options: number|object): db_sqlite;
@@ -1197,7 +1208,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, parse_template, http_apply_range, get_git_hashes } from 'spooder';
+import { http_serve, cache_http, parse_template, http_apply_range, git_get_hashes } from 'spooder';
 import path from 'node:path';
 
 const server = http_serve(80);
@@ -1209,7 +1220,7 @@ const cache = cache_http({
 });
 
 const base_file = await Bun.file('./html/base_template.html').text();
-const git_hash_table = await get_git_hashes();
+const git_hash_table = await git_get_hashes();
 
 async function default_handler(status_code: number): Promise<Response> {
 	const error_text = HTTP_STATUS_CODE[status_code] as string;
@@ -1243,7 +1254,7 @@ server.dir('/static', './static', async (file_path, file, stat, request) => {
 	const ext = path.extname(file_path);
 	if (ext === '.css' || ext === '.js') {
 		const content = await parse_template(await file.text(), {
-			asset: (file) => git_hash_table[file]
+			cache_bust: (file) => `${file}?v=${git_hash_table[file]}`
 		}, true);
 
 		return new Response(content, {
@@ -1302,7 +1313,11 @@ server.bootstrap({
 		error_page: Bun.file('./html/error.html')
 	},
 	
-	cache_bust: true,
+	cache_bust: { // true or options
+		format: '$file#$hash', // default: $file?v=$hash
+		hash_length: 20, // default: 7
+		prefix: 'bust' // default: cache_bust
+	},
 
 	static: {
 		directory: './static',
@@ -1401,29 +1416,29 @@ cache: {
 }
 ```
 
-##### `cache_bust?: boolean`
-When enabled, automatically generates git hash-based cache busting for static assets using dynamic template resolvers.
+##### `cache_bust?: CacheBustOptions | boolean`
+Enables the use of the [`cache_bust()`](#api-cache-busting) API inside templates using the ``{{cache_bust=file}}`` directive.
 
-```ts
-cache_bust: true
+```html
+<link href="{{cache_bust=static/css/style.css}}">
+<script src="{{cache_bust=static/js/app.js}}"></script>
+<img src="{{cache_bust=static/images/logo.png}}">
 ```
 
-With `cache_bust` enabled, you can use the `{{asset=filename}}` template function to generate cache-busted URLs:
+Since this uses the [`cache_bust()`](#api-cache-busting) API internally, it is effected by the `cache_bust_set_hash_length` and `cache_bust_set_format` global functions.
 
-**Usage:**
-```ts
-cache_bust: true
-// Creates dynamic asset resolver: {{asset=static/css/style.css}} -> "static/css/style.css?v=a1b2c3d"
-```
+Setting `cache_bust` to `true` assumes the normal defaults, however this can be customized by providing an options object.
 
-**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}}">
+```ts
+cache_bust: { // true or options
+	format: '$file#$hash', // default: $file?v=$hash
+	hash_length: 20, // default: 7
+	prefix: 'bust' // default: cache_bust
+},
 ```
 
-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.
+> ![IMPORTANT]
+> `format` and `hash_length` internally call `cache_bust_set_format` and `cache_bust_set_hash_length` respectively, so these values will effect `cache_bust()` globally.
 
 ##### `error?: object`
 Optional error page configuration:
@@ -1962,6 +1977,34 @@ const html = await parse_template(template, replacements);
 </ul>
 ```
 
+#### Simple Array Iteration
+
+For simple arrays containing strings, you can iterate directly over the array items:
+
+```ts
+const template = `
+	<ul>
+		<t-for items="fruits" as="fruit">
+			<li>{{fruit}}</li>
+		</t-for>
+	</ul>
+`;
+
+const replacements = {
+	fruits: ['apple', 'banana', 'orange']
+};
+
+const html = await parse_template(template, replacements);
+```
+
+```html
+<ul>
+	<li>apple</li>
+	<li>banana</li>
+	<li>orange</li>
+</ul>
+```
+
 #### Dot Notation Property Access
 
 You can access nested object properties using dot notation:
@@ -2002,26 +2045,73 @@ await parse_template(..., {
 </t-for>
 ```
 
+<a id="api-cache-busting"></a>
+## API > Cache Busting
+
+### 🔧 ``cache_bust(string: path, format: string): string``
+
+Appends a hash-suffix to the provided string, formatted by default as a query parameter, for cache-busting purposes.
+
+```ts
+cache_bust('static/my_image.png'); // > static/my_image.png?v=123fea
+```
+
+> ![NOTE]
+> Internally `cache_bust()` uses `git_get_hashes()` to hash paths, requiring the input `path` to be a valid git path. If the path cannot be resolved in git, an empty hash is substituted.
+
+### 🔧 ``cache_bust_set_format(format: string): void``
+
+The default format for used for `cache_bust()` is `$file?v=$hash`, this can be customized per-call with the `format` parameter, or globally using `cache_bust_set_format()`
 
-### 🔧 ``get_git_hashes(length: number): Promise<Record<string, string>>``
+```ts
+cache_bust('dogs.txt'); // > dogs.txt?v=fff
+cache_bust('dogs.txt', '$file?hash=$hash'); // > dogs.txt?hash=fff
+
+cache_bust_set_format('$file#$hash');
+cache_bust('dogs.txt'); // > dogs#fff
+```
+
+### 🔧 ``cache_bust_set_hash_length(length: number): void``
+
+The default hash-length used by `cache_bust()` is 7. This can be changed with `cache_bust_set_hash_length()`.
+
+> ![NOTE]
+> Hashes are cached once at the specified length, therefore `cache_bust_set_hash_length()` must be called before calling `cache_bust()` and has no effect calling it after.
+
+```ts
+cache_bust_set_hash_length(10);
+cache_bust('dogs.txt'); // > dogs.txt?v=ffffffffff
+```
+
+### 🔧 ``cache_bust_get_hash_table(): Record<string, string>``
+
+This function returns the internal hash table used by `cache_bust()`. This is exposed to userland in the event that you which to use the hashes for other purposes, avoiding the need to call and store `git_get_hashes()` twice.
+
+<a id="api-templating"></a>
+## API > Git
+
+### 🔧 ``git_get_hashes(length: number): Promise<Record<string, string>>``
+
+### 🔧 ``git_get_hashes_sync(length: number): Record<string, string>``
 
 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.
+> Internally `git_get_hashes()` uses `git ls-tree -r HEAD`, so the working directory must be a git repository.
 
 ```ts
-const hashes = await get_git_hashes(7);
+const hashes = await git_get_hashes(7);
 // { 'docs/project-logo.png': '754d9ea' }
 ```
 
 You can specify the hash length (default is 7 characters for short hashes):
 
 ```ts
-const full_hashes = await get_git_hashes(40);
+const full_hashes = await git_get_hashes(40);
 // { 'docs/project-logo.png': 'd65c52a41a75db43e184d2268c6ea9f9741de63e' }
 ```
 
+
 <a id="api-database"></a>
 <a id="api-database-interface"></a>
 ## API > Database

package/package.json

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

package/src/api.ts

@@ -556,8 +556,36 @@ async function replace_async(str: string, regex: RegExp, replacer_fn: (match: st
 	
 	return result;
 }
+// endregion
+
+// region cache busting
+let cache_bust_map: Record<string, string> | null = null;
+let cache_bust_global_length = 7;
+let cache_bust_global_format = '$file?v=$hash';
+
+export function cache_bust_get_hash_table(): Record<string, string> {
+	if (cache_bust_map === null)
+		cache_bust_map = git_get_hashes_sync(cache_bust_global_length);
+
+	return cache_bust_map;
+}
+
+export function cache_bust(path: string, format = cache_bust_global_format): string {
+	const hash = cache_bust_get_hash_table()[path] || '';
+	return format.replace('$file', path).replace('$hash', hash);
+}
+
+export function cache_bust_set_hash_length(length: number): void {
+	cache_bust_global_length = length;
+}
 
-export async function get_git_hashes(length = 7): Promise<Record<string, string>> {
+export function cache_bust_set_format(format: string): void {
+	cache_bust_global_format = format;
+}
+// endregion
+
+// region git
+export async function git_get_hashes(length = 7): Promise<Record<string, string>> {
 	const cmd = ['git', 'ls-tree', '-r', 'HEAD'];
 	const process = Bun.spawn(cmd, {
 		stdout: 'pipe',
@@ -567,7 +595,7 @@ export async function get_git_hashes(length = 7): Promise<Record<string, string>
 	await process.exited;
 	
 	if (process.exitCode as number > 0)
-		throw new Error('get_git_hashes() failed, `' + cmd.join(' ') + '` exited with non-zero exit code.');
+		throw new Error('git_get_hashes() failed, `' + cmd.join(' ') + '` exited with non-zero exit code.');
 	
 	const stdout = await Bun.readableStreamToText(process.stdout as ReadableStream);
 	const hash_map: Record<string, string> = {};
@@ -581,6 +609,27 @@ export async function get_git_hashes(length = 7): Promise<Record<string, string>
 	return hash_map;
 }
 
+export function git_get_hashes_sync(length = 7): Record<string, string> {
+	const cmd = ['git', 'ls-tree', '-r', 'HEAD'];
+	const process = Bun.spawnSync(cmd, {
+		stdout: 'pipe',
+		stderr: 'pipe'
+	});
+	
+	if (process.exitCode > 0)
+		throw new Error('git_get_hashes_sync() failed, `' + cmd.join(' ') + '` exited with non-zero exit code.');
+	
+	const stdout = process.stdout.toString();
+	const hash_map: Record<string, string> = {};
+	
+	const regex = /([^\s]+)\s([^\s]+)\s([^\s]+)\t(.+)/g;
+	let match: RegExpExecArray | null;
+	
+	while (match = regex.exec(stdout))
+		hash_map[match[4]] = match[3].substring(0, length);
+	
+	return hash_map;
+}
 // endregion
 
 // region serving
@@ -1004,11 +1053,19 @@ type BootstrapRoute = {
 	subs?: Record<string, BootstrapSub>;
 };
 
+type BootstrapCacheBust = {
+	prefix?: string;
+	hash_length?: number;
+	format?: string;
+};
+
 type BootstrapOptions = {
 	base?: string | BunFile;
 	routes: Record<string, BootstrapRoute>;
 	cache?: ReturnType<typeof cache_http> | CacheOptions;
-	cache_bust?: boolean;
+
+	cache_bust?: boolean | BootstrapCacheBust;
+
 	error?: {
 		use_canary_reporting?: boolean;
 		error_page: string | BunFile;
@@ -1428,17 +1485,19 @@ export function http_serve(port: number, hostname?: string) {
 		
 		/* Bootstrap a static web server */
 		bootstrap: async function(options: BootstrapOptions) {
-			let git_hash_table: Record<string, string> = {};
-			let cache_bust_subs = {};
+			let cache_bust_subs: Record<string, ReplacementValue> = {};
 			
-			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 cache_bust_opts = options.cache_bust;
+			if (typeof cache_bust_opts === 'object' && cache_bust_opts !== null) {
+				if (typeof cache_bust_opts.hash_length === 'number')
+					cache_bust_set_hash_length(cache_bust_opts.hash_length);
+
+				if (typeof cache_bust_opts.format === 'string')
+					cache_bust_set_format(cache_bust_opts.format);
+
+				cache_bust_subs[cache_bust_opts.prefix ?? 'cache_bust'] = cache_bust;
+			} else if (cache_bust_opts === true) {
+				cache_bust_subs = { cache_bust };
 			}
 			
 			const global_sub_table = sub_table_merge(cache_bust_subs, options.global_subs);