From 3100826d9b214c6100f55ea41e6ec676f478da06 Mon Sep 17 00:00:00 2001
From: Alex Yang <himself65@outlook.com>
Date: Thu, 22 Jan 2026 12:19:46 -0800
Subject: [PATCH] chore(core): improve `runInBackground` API type (#7533)

---
 .../better-auth/src/plugins/api-key/api-key.test.ts  | 12 ++++++------
 .../src/plugins/api-key/routes/verify-api-key.ts     |  8 +++-----
 packages/core/src/types/context.ts                   |  7 ++++---
 packages/core/src/types/init-options.ts              |  2 +-
 4 files changed, 14 insertions(+), 15 deletions(-)

diff --git a/packages/better-auth/src/plugins/api-key/api-key.test.ts b/packages/better-auth/src/plugins/api-key/api-key.test.ts
index 1636c244b9..e4c5d19f5b 100644
--- a/packages/better-auth/src/plugins/api-key/api-key.test.ts
+++ b/packages/better-auth/src/plugins/api-key/api-key.test.ts
@@ -2917,11 +2917,11 @@ describe("api-key", async () => {
 
 	describe("deferUpdates option", () => {
 		it("should defer updates when deferUpdates is enabled with global backgroundTasks", async () => {
-			const deferredPromises: Array<Promise<void>> = [];
+			const deferredPromises: Array<Promise<unknown>> = [];
 			const { auth, signInWithTestUser } = await getTestInstance({
 				advanced: {
 					backgroundTasks: {
-						handler: (p: Promise<void>) => {
+						handler: (p: Promise<unknown>) => {
 							deferredPromises.push(p);
 						},
 					},
@@ -2957,11 +2957,11 @@ describe("api-key", async () => {
 		});
 
 		it("should still validate rate limits correctly with deferred updates", async () => {
-			const deferredPromises: Array<Promise<void>> = [];
+			const deferredPromises: Array<Promise<unknown>> = [];
 			const { auth, signInWithTestUser } = await getTestInstance({
 				advanced: {
 					backgroundTasks: {
-						handler: (p: Promise<void>) => {
+						handler: (p: Promise<unknown>) => {
 							deferredPromises.push(p);
 						},
 					},
@@ -3003,11 +3003,11 @@ describe("api-key", async () => {
 		});
 
 		it("should defer remaining count updates", async () => {
-			const deferredPromises: Array<Promise<void>> = [];
+			const deferredPromises: Array<Promise<unknown>> = [];
 			const { auth, signInWithTestUser } = await getTestInstance({
 				advanced: {
 					backgroundTasks: {
-						handler: (p: Promise<void>) => {
+						handler: (p: Promise<unknown>) => {
 							deferredPromises.push(p);
 						},
 					},
diff --git a/packages/better-auth/src/plugins/api-key/routes/verify-api-key.ts b/packages/better-auth/src/plugins/api-key/routes/verify-api-key.ts
index 2820464eed..01fff37db5 100644
--- a/packages/better-auth/src/plugins/api-key/routes/verify-api-key.ts
+++ b/packages/better-auth/src/plugins/api-key/routes/verify-api-key.ts
@@ -218,11 +218,9 @@ export async function validateApiKey({
 
 	if (opts.deferUpdates) {
 		ctx.context.runInBackground(
-			performUpdate()
-				.then(() => {})
-				.catch((error) => {
-					ctx.context.logger.error("Failed to update API key:", error);
-				}),
+			performUpdate().catch((error) => {
+				ctx.context.logger.error("Failed to update API key:", error);
+			}),
 		);
 		newApiKey = updated;
 	} else {
diff --git a/packages/core/src/types/context.ts b/packages/core/src/types/context.ts
index 75e2fbdd52..039ef6fd03 100644
--- a/packages/core/src/types/context.ts
+++ b/packages/core/src/types/context.ts
@@ -12,6 +12,7 @@ import type { DBAdapter, Where } from "../db/adapter";
 import type { createLogger } from "../env";
 import type { OAuthProvider } from "../oauth2";
 import type { BetterAuthCookie, BetterAuthCookies } from "./cookie";
+import type { Awaitable } from "./helper";
 import type {
 	BetterAuthOptions,
 	BetterAuthRateLimitOptions,
@@ -299,7 +300,7 @@ export type AuthContext<Options extends BetterAuthOptions = BetterAuthOptions> =
 			 * This is inferred from the `options.advanced?.backgroundTasks?.handler` option.
 			 * Defaults to a no-op that just runs the promise.
 			 */
-			runInBackground: (promise: Promise<void>) => void;
+			runInBackground: (promise: Promise<unknown>) => void;
 			/**
 			 * Runs a task in the background if `runInBackground` is configured,
 			 * otherwise awaits the task directly.
@@ -309,6 +310,6 @@ export type AuthContext<Options extends BetterAuthOptions = BetterAuthOptions> =
 			 * mitigation), but still ensure the operation completes.
 			 */
 			runInBackgroundOrAwait: (
-				promise: Promise<unknown> | Promise<void> | void | unknown,
-			) => Promise<unknown>;
+				promise: Promise<unknown> | void,
+			) => Awaitable<unknown>;
 		};
diff --git a/packages/core/src/types/init-options.ts b/packages/core/src/types/init-options.ts
index 8dcd8d8af5..ce87014ba8 100644
--- a/packages/core/src/types/init-options.ts
+++ b/packages/core/src/types/init-options.ts
@@ -328,7 +328,7 @@ export type BetterAuthAdvancedOptions = {
 	 * }
 	 */
 	backgroundTasks?: {
-		handler: (promise: Promise<void>) => void;
+		handler: (promise: Promise<unknown>) => void;
 	};
 	/**
 	 * Skip trailing slash validation in route matching