spooder 4.2.0 → 4.2.2

package/README.md

@@ -430,6 +430,7 @@ In addition to the information provided by the developer, `spooder` also include
 	- [`ErrorWithMetadata(message: string, metadata: object)`](#api-error-handling-error-with-metadata)
 	- [`caution(err_message_or_obj: string | object, ...err: object[]): Promise<void>`](#api-error-handling-caution)
 	- [`panic(err_message_or_obj: string | object, ...err: object[]): Promise<void>`](#api-error-handling-panic)
+	- [`safe(fn: Callable): Promise<void>`](#api-error-handling-safe)
 - [API > Content](#api-content)
 	- [`parse_template(template: string, replacements: Record<string, string>): string`](#api-content-parse-template)
 	- [`generate_hash_subs(length: number, prefix: string): Promise<Record<string, string>>`](#api-content-generate-hash-subs)
@@ -872,6 +873,30 @@ try {
 }
 ```
 
+<a id="api-error-handling-safe"></a>
+### 🔧 `safe(fn: Callable): Promise<void>`
+
+`safe()` is a utility function that wraps a "callable" and calls `caution()` if it throws an error.
+
+> ![NOTE]
+> This utility is primarily intended to be used to reduce boilerplate for fire-and-forget functions that you want to be notified about if they fail. 
+
+```ts
+safe(async (() => {
+	// This code will run async and any errors will invoke caution().
+});
+```
+
+`safe()` supports both async and sync callables, as well as Promise objects. `safe()` can also used with `await`.
+
+```ts
+await safe(() => {
+	return new Promise((resolve, reject) => {
+		// Do stuff.
+	});
+});
+```
+
 <a id="api-content"></a>
 ## API > Content
 
@@ -962,7 +987,7 @@ 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);
+	return parse_template('Hello world {$hash=docs/project-logo.png}', hash_sub_table);
 });
 ```
 
@@ -983,13 +1008,13 @@ generate_hash_subs(40).then(...);
 > [!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.
+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);
+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);
+	return parse_template('Hello world {$#docs/project-logo.png}', hash_sub_table);
 });
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "spooder",
 	"type": "module",
-	"version": "4.2.0",
+	"version": "4.2.2",
 	"exports": {
 		".": {
 			"bun": "./src/api.ts",

package/src/api.d.ts

@@ -15,6 +15,9 @@ export declare class ErrorWithMetadata extends Error {
 }
 export declare function panic(err_message_or_obj: string | object, ...err: object[]): Promise<void>;
 export declare function caution(err_message_or_obj: string | object, ...err: object[]): Promise<void>;
+type CallableFunction = (...args: any[]) => any;
+type Callable = Promise<any> | CallableFunction;
+export declare function safe(target_fn: Callable): Promise<void>;
 export declare function parse_template(template: string, replacements: Record<string, string | Array<string>>): string;
 export declare function generate_hash_subs(length?: number, prefix?: string): Promise<Record<string, string>>;
 type CookieOptions = {

package/src/api.ts

@@ -89,6 +89,20 @@ export async function caution(err_message_or_obj: string | object, ...err: objec
 	await handle_error('caution: ', err_message_or_obj, ...err);
 }
 
+type CallableFunction = (...args: any[]) => any;
+type Callable = Promise<any> | CallableFunction;
+
+export async function safe(target_fn: Callable) {
+	try {
+		if (target_fn instanceof Promise)
+			await target_fn;
+		else
+			await target_fn();
+	} catch (e) {
+		caution(e as Error);
+	}
+}
+
 export function parse_template(template: string, replacements: Record<string, string | Array<string>>): string {
 	let result = '';
 	let buffer = '';
@@ -109,26 +123,30 @@ export function parse_template(template: string, replacements: Record<string, st
 				const loop_key = buffer.substring(4);
 
 				const loop_entries = replacements[loop_key];
-				if (loop_entries !== undefined) {
-					const loop_content_start_index = i + 1;
-					const loop_close_index = template.indexOf('{/for}', loop_content_start_index);
-					const loop_content = template.substring(loop_content_start_index, loop_close_index);
-
-					// More performat than replaceAll on larger arrays (and equal on tiny arrays).
-					const content_parts = loop_content.split('%s');
-					const indicies = [] as Array<number>;
-
-					for (let j = 0; j < content_parts.length; j++)
-						if (content_parts[j] === '%s')
-							indicies.push(j);
-
-					for (const loop_entry of loop_entries)
-						for (const index of indicies)
-							content_parts[index] = loop_entry;
-
-					i += loop_content.length + 6;
-				} else {
+				const loop_content_start_index = i + 1;
+				const loop_close_index = template.indexOf('{/for}', loop_content_start_index);
+				
+				if (loop_close_index === -1) {
 					result += '{$' + buffer + '}';
+				} else {
+					const loop_content = template.substring(loop_content_start_index, loop_close_index);
+					if (loop_entries !== undefined) {
+						// More performat than replaceAll on larger arrays (and equal on tiny arrays).
+						const content_parts = loop_content.split('%s');
+						const indicies = [] as Array<number>;
+	
+						for (let j = 0; j < content_parts.length; j++)
+							if (content_parts[j] === '%s')
+								indicies.push(j);
+	
+						for (const loop_entry of loop_entries)
+							for (const index of indicies)
+								content_parts[index] = loop_entry;
+	
+						i += loop_content.length + 6;
+					} else {
+						result += '{$' + buffer + '}' + loop_content + '{/for}';
+					}
 				}
 			} else {
 				result += replacements[buffer] ?? '{$' + buffer + '}';
@@ -144,7 +162,7 @@ export function parse_template(template: string, replacements: Record<string, st
 	return result;
 }
 
-export async function generate_hash_subs(length = 7, prefix = 'hash='): Promise<Record<string, string>> {
+export async function generate_hash_subs(length = 7, prefix = '$hash='): Promise<Record<string, string>> {
 	const cmd = ['git', 'ls-tree', '-r', 'HEAD'];
 	const process = Bun.spawn(cmd, {
 		stdout: 'pipe',