spooder 4.2.0 → 4.2.1

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
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "spooder",
 	"type": "module",
-	"version": "4.2.0",
+	"version": "4.2.1",
 	"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 = '';