@better-auth/core 1.5.5 → 1.5.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.5.5",
+  "version": "1.5.6",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -87,6 +87,11 @@
       "dev-source": "./src/oauth2/index.ts",
       "types": "./dist/oauth2/index.d.mts",
       "default": "./dist/oauth2/index.mjs"
+    },
+    "./instrumentation": {
+      "dev-source": "./src/instrumentation/index.ts",
+      "types": "./dist/instrumentation/index.d.mts",
+      "default": "./dist/instrumentation/index.mjs"
     }
   },
   "typesVersions": {
@@ -126,26 +131,34 @@
       ],
       "oauth2": [
         "dist/oauth2/index.d.mts"
+      ],
+      "instrumentation": [
+        "dist/instrumentation/index.d.mts"
       ]
     }
   },
   "dependencies": {
+    "@opentelemetry/semantic-conventions": "^1.39.0",
     "@standard-schema/spec": "^1.1.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@better-auth/utils": "0.3.1",
     "@better-fetch/fetch": "1.1.21",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.0",
+    "@opentelemetry/sdk-trace-node": "^1.30.0",
     "better-call": "1.3.2",
     "@cloudflare/workers-types": "^4.20250121.0",
     "jose": "^6.1.3",
-    "kysely": "^0.28.11",
+    "kysely": "^0.28.12",
     "nanostores": "^1.1.1",
     "tsdown": "0.21.0-beta.2"
   },
   "peerDependencies": {
     "@better-auth/utils": "0.3.1",
     "@better-fetch/fetch": "1.1.21",
+    "@opentelemetry/api": "^1.9.0",
     "better-call": "1.3.2",
     "@cloudflare/workers-types": ">=4",
     "jose": "^6.1.0",

package/src/db/adapter/factory.ts

@@ -1,5 +1,10 @@
 import { createLogger, getColorDepth, TTY_COLORS } from "../../env";
 import { BetterAuthError } from "../../error";
+import {
+	ATTR_DB_COLLECTION_NAME,
+	ATTR_DB_OPERATION_NAME,
+	withSpan,
+} from "../../instrumentation";
 import type { BetterAuthOptions } from "../../types";
 import { safeJSONParse } from "../../utils/json";
 import { getAuthTables } from "../get-tables";
@@ -765,20 +770,36 @@ export const createAdapterFactory =
 			});
 			try {
 				if (joinConfig.relation === "one-to-one") {
-					result = await adapterInstance.findOne<Record<string, any>>({
-						model: modelName,
-						where: where,
-					});
+					result = await withSpan(
+						`db findOne ${modelName}`,
+						{
+							[ATTR_DB_OPERATION_NAME]: "findOne",
+							[ATTR_DB_COLLECTION_NAME]: modelName,
+						},
+						() =>
+							adapterInstance.findOne<Record<string, any>>({
+								model: modelName,
+								where: where,
+							}),
+					);
 				} else {
 					const limit =
 						joinConfig.limit ??
 						options.advanced?.database?.defaultFindManyLimit ??
 						100;
-					result = await adapterInstance.findMany<Record<string, any>>({
-						model: modelName,
-						where: where,
-						limit,
-					});
+					result = await withSpan(
+						`db findMany ${modelName}`,
+						{
+							[ATTR_DB_OPERATION_NAME]: "findMany",
+							[ATTR_DB_COLLECTION_NAME]: modelName,
+						},
+						() =>
+							adapterInstance.findMany<Record<string, any>>({
+								model: modelName,
+								where: where,
+								limit,
+							}),
+					);
 				}
 			} catch (error) {
 				logger.error(`Failed to query fallback join for model ${modelName}:`, {
@@ -879,7 +900,14 @@ export const createAdapterFactory =
 					`${formatMethod("create")} ${formatAction("Parsed Input")}:`,
 					{ model, data },
 				);
-				const res = await adapterInstance.create<T>({ data, model });
+				const res = await withSpan(
+					`db create ${model}`,
+					{
+						[ATTR_DB_OPERATION_NAME]: "create",
+						[ATTR_DB_COLLECTION_NAME]: model,
+					},
+					() => adapterInstance.create<T>({ data, model }),
+				);
 				debugLog(
 					{ method: "create" },
 					`${formatTransactionId(thisTransactionId)} ${formatStep(3, 4)}`,
@@ -937,11 +965,19 @@ export const createAdapterFactory =
 					`${formatMethod("update")} ${formatAction("Parsed Input")}:`,
 					{ model, data },
 				);
-				const res = await adapterInstance.update<T>({
-					model,
-					where,
-					update: data,
-				});
+				const res = await withSpan(
+					`db update ${model}`,
+					{
+						[ATTR_DB_OPERATION_NAME]: "update",
+						[ATTR_DB_COLLECTION_NAME]: model,
+					},
+					() =>
+						adapterInstance.update<T>({
+							model,
+							where,
+							update: data,
+						}),
+				);
 				debugLog(
 					{ method: "update" },
 					`${formatTransactionId(thisTransactionId)} ${formatStep(3, 4)}`,
@@ -1000,11 +1036,19 @@ export const createAdapterFactory =
 					{ model, data },
 				);
 
-				const updatedCount = await adapterInstance.updateMany({
-					model,
-					where,
-					update: data,
-				});
+				const updatedCount = await withSpan(
+					`db updateMany ${model}`,
+					{
+						[ATTR_DB_OPERATION_NAME]: "updateMany",
+						[ATTR_DB_COLLECTION_NAME]: model,
+					},
+					() =>
+						adapterInstance.updateMany({
+							model,
+							where,
+							update: data,
+						}),
+				);
 				debugLog(
 					{ method: "updateMany" },
 					`${formatTransactionId(thisTransactionId)} ${formatStep(3, 4)}`,
@@ -1063,12 +1107,20 @@ export const createAdapterFactory =
 					{ model, where, select, join },
 				);
 
-				const res = await adapterInstance.findOne<T>({
-					model,
-					where,
-					select,
-					join: passJoinToAdapter ? join : undefined,
-				});
+				const res = await withSpan(
+					`db findOne ${model}`,
+					{
+						[ATTR_DB_OPERATION_NAME]: "findOne",
+						[ATTR_DB_COLLECTION_NAME]: model,
+					},
+					() =>
+						adapterInstance.findOne<T>({
+							model,
+							where,
+							select,
+							join: passJoinToAdapter ? join : undefined,
+						}),
+				);
 				debugLog(
 					{ method: "findOne" },
 					`${formatTransactionId(thisTransactionId)} ${formatStep(2, 3)}`,
@@ -1142,15 +1194,23 @@ export const createAdapterFactory =
 					`${formatMethod("findMany")}:`,
 					{ model, where, limit, sortBy, offset, join },
 				);
-				const res = await adapterInstance.findMany<T>({
-					model,
-					where,
-					limit: limit,
-					select,
-					sortBy,
-					offset,
-					join: passJoinToAdapter ? join : undefined,
-				});
+				const res = await withSpan(
+					`db findMany ${model}`,
+					{
+						[ATTR_DB_OPERATION_NAME]: "findMany",
+						[ATTR_DB_COLLECTION_NAME]: model,
+					},
+					() =>
+						adapterInstance.findMany<T>({
+							model,
+							where,
+							limit: limit,
+							select,
+							sortBy,
+							offset,
+							join: passJoinToAdapter ? join : undefined,
+						}),
+				);
 				debugLog(
 					{ method: "findMany" },
 					`${formatTransactionId(thisTransactionId)} ${formatStep(2, 3)}`,
@@ -1197,10 +1257,14 @@ export const createAdapterFactory =
 					`${formatMethod("delete")}:`,
 					{ model, where },
 				);
-				await adapterInstance.delete({
-					model,
-					where,
-				});
+				await withSpan(
+					`db delete ${model}`,
+					{
+						[ATTR_DB_OPERATION_NAME]: "delete",
+						[ATTR_DB_COLLECTION_NAME]: model,
+					},
+					() => adapterInstance.delete({ model, where }),
+				);
 				debugLog(
 					{ method: "delete" },
 					`${formatTransactionId(thisTransactionId)} ${formatStep(2, 2)}`,
@@ -1230,10 +1294,14 @@ export const createAdapterFactory =
 					`${formatMethod("deleteMany")} ${formatAction("DeleteMany")}:`,
 					{ model, where },
 				);
-				const res = await adapterInstance.deleteMany({
-					model,
-					where,
-				});
+				const res = await withSpan(
+					`db deleteMany ${model}`,
+					{
+						[ATTR_DB_OPERATION_NAME]: "deleteMany",
+						[ATTR_DB_COLLECTION_NAME]: model,
+					},
+					() => adapterInstance.deleteMany({ model, where }),
+				);
 				debugLog(
 					{ method: "deleteMany" },
 					`${formatTransactionId(thisTransactionId)} ${formatStep(2, 2)}`,
@@ -1267,10 +1335,14 @@ export const createAdapterFactory =
 						where,
 					},
 				);
-				const res = await adapterInstance.count({
-					model,
-					where,
-				});
+				const res = await withSpan(
+					`db count ${model}`,
+					{
+						[ATTR_DB_OPERATION_NAME]: "count",
+						[ATTR_DB_COLLECTION_NAME]: model,
+					},
+					() => adapterInstance.count({ model, where }),
+				);
 				debugLog(
 					{ method: "count" },
 					`${formatTransactionId(thisTransactionId)} ${formatStep(2, 2)}`,

package/src/db/adapter/get-id-field.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it } from "vitest";
+import type { BetterAuthOptions } from "../../types";
+import type { BetterAuthDBSchema } from "../type";
+import { initGetIdField } from "./get-id-field";
+
+const minimalSchema: BetterAuthDBSchema = {
+	user: {
+		modelName: "user",
+		fields: {
+			name: { type: "string" },
+			email: { type: "string" },
+		},
+	},
+};
+
+const uuidRegex =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function getField(
+	options: BetterAuthOptions,
+	initExtra?: Partial<Parameters<typeof initGetIdField>[0]>,
+	fieldExtra?: { customModelName?: string; forceAllowId?: boolean },
+) {
+	const idField = initGetIdField({
+		schema: minimalSchema,
+		options,
+		...initExtra,
+	});
+	return idField({
+		customModelName: fieldExtra?.customModelName ?? "user",
+		forceAllowId: fieldExtra?.forceAllowId,
+	});
+}
+
+describe("defaultValue priority", () => {
+	it("should return undefined when disableIdGeneration is true", () => {
+		const field = getField(
+			{ database: {} as any },
+			{ disableIdGeneration: true },
+		);
+		expect(field.defaultValue).toBeUndefined();
+	});
+
+	it("should return undefined when generateId is false", () => {
+		const value = getField({
+			database: {} as any,
+			advanced: { database: { generateId: false } },
+		}).defaultValue?.();
+		expect(value).toBeUndefined();
+	});
+
+	it("should return undefined when generateId is 'serial'", () => {
+		const value = getField({
+			database: {} as any,
+			advanced: { database: { generateId: "serial" } },
+		}).defaultValue?.();
+		expect(value).toBeUndefined();
+	});
+
+	it("should use generateId function over 'uuid' and customIdGenerator", () => {
+		const value = getField(
+			{
+				database: {} as any,
+				advanced: { database: { generateId: () => "fn-id" } },
+			},
+			{ customIdGenerator: () => "adapter-id" },
+		).defaultValue?.();
+		expect(value).toBe("fn-id");
+	});
+
+	it("should use 'uuid' over customIdGenerator", () => {
+		const value = getField(
+			{
+				database: {} as any,
+				advanced: { database: { generateId: "uuid" } },
+			},
+			{ customIdGenerator: () => "adapter-id", supportsUUIDs: false },
+		).defaultValue?.();
+		expect(value).toMatch(uuidRegex);
+	});
+
+	it("should use customIdGenerator when generateId is not set", () => {
+		const value = getField(
+			{ database: {} as any },
+			{ customIdGenerator: () => "adapter-id" },
+		).defaultValue?.();
+		expect(value).toBe("adapter-id");
+	});
+
+	it("should fall back to default id generation", () => {
+		const value = getField({ database: {} as any }).defaultValue?.();
+		expect(typeof value).toBe("string");
+		expect(value).not.toMatch(uuidRegex);
+	});
+});
+
+describe("type and required", () => {
+	it("should have type 'number' when generateId is 'serial'", () => {
+		const field = getField({
+			database: {} as any,
+			advanced: { database: { generateId: "serial" } },
+		});
+		expect(field.type).toBe("number");
+		expect(field.required).toBe(false);
+	});
+
+	it("should have type 'string' by default", () => {
+		const field = getField({ database: {} as any });
+		expect(field.type).toBe("string");
+		expect(field.required).toBe(true);
+	});
+
+	it("should not generate id when useUUIDs and supportsUUIDs", () => {
+		const field = getField(
+			{
+				database: {} as any,
+				advanced: { database: { generateId: "uuid" } },
+			},
+			{ supportsUUIDs: true },
+		);
+		expect(field.required).toBe(false);
+		expect(field.defaultValue).toBeUndefined();
+	});
+});
+
+describe("transform.input", () => {
+	it("should return undefined for falsy value", () => {
+		const field = getField({ database: {} as any });
+		expect(field.transform.input(undefined)).toBeUndefined();
+		expect(field.transform.input(null)).toBeUndefined();
+		expect(field.transform.input("")).toBeUndefined();
+	});
+
+	it("should return value as-is by default", () => {
+		const field = getField({ database: {} as any });
+		expect(field.transform.input("some-id")).toBe("some-id");
+	});
+
+	describe("serial", () => {
+		it("should convert string to number", () => {
+			const field = getField({
+				database: {} as any,
+				advanced: { database: { generateId: "serial" } },
+			});
+			expect(field.transform.input("42")).toBe(42);
+		});
+
+		it("should return undefined for non-numeric string", () => {
+			const field = getField({
+				database: {} as any,
+				advanced: { database: { generateId: "serial" } },
+			});
+			expect(field.transform.input("not-a-number")).toBeUndefined();
+		});
+	});
+
+	describe("uuid", () => {
+		it("should return value as-is when shouldGenerateId and not forceAllowId", () => {
+			const field = getField(
+				{
+					database: {} as any,
+					advanced: { database: { generateId: "uuid" } },
+				},
+				{ supportsUUIDs: false },
+			);
+			const uuid = crypto.randomUUID();
+			expect(field.transform.input(uuid)).toBe(uuid);
+		});
+
+		it("should return undefined when supportsUUIDs (DB handles it)", () => {
+			const field = getField(
+				{
+					database: {} as any,
+					advanced: { database: { generateId: "uuid" } },
+				},
+				{ supportsUUIDs: true },
+			);
+			expect(field.transform.input("some-value")).toBeUndefined();
+		});
+
+		it("should accept valid UUID when forceAllowId is true", () => {
+			const uuid = crypto.randomUUID();
+			const field = getField(
+				{
+					database: {} as any,
+					advanced: { database: { generateId: "uuid" } },
+				},
+				{ supportsUUIDs: false },
+				{ forceAllowId: true },
+			);
+			expect(field.transform.input(uuid)).toBe(uuid);
+		});
+
+		it("should generate new UUID for non-string value when DB doesn't support UUIDs", () => {
+			const field = getField(
+				{
+					database: {} as any,
+					advanced: { database: { generateId: "uuid" } },
+				},
+				{ supportsUUIDs: false },
+				{ forceAllowId: true },
+			);
+			const result = field.transform.input(123);
+			expect(result).toMatch(uuidRegex);
+		});
+	});
+});
+
+describe("transform.output", () => {
+	it("should return undefined for falsy value", () => {
+		const field = getField({ database: {} as any });
+		expect(field.transform.output(undefined)).toBeUndefined();
+		expect(field.transform.output(null)).toBeUndefined();
+		expect(field.transform.output("")).toBeUndefined();
+	});
+
+	it("should convert value to string", () => {
+		const field = getField({ database: {} as any });
+		expect(field.transform.output(123)).toBe("123");
+		expect(field.transform.output("abc")).toBe("abc");
+	});
+});

package/src/db/adapter/get-id-field.ts

@@ -57,18 +57,29 @@ export const initGetIdField = ({
 						defaultValue() {
 							if (disableIdGeneration) return undefined;
 							const generateId = options.advanced?.database?.generateId;
-							if (generateId === false || useNumberId) return undefined;
+
+							// let the database handle id generation
+							if (generateId === false || generateId === "serial")
+								return undefined;
+
+							// user-provided function takes highest priority
 							if (typeof generateId === "function") {
 								return generateId({
 									model,
 								});
 							}
-							if (customIdGenerator) {
-								return customIdGenerator({ model });
-							}
+
+							// user-provided "uuid" option
 							if (generateId === "uuid") {
 								return crypto.randomUUID();
 							}
+
+							// database adapter-level custom id generator
+							if (customIdGenerator) {
+								return customIdGenerator({ model });
+							}
+
+							// fallback to default id generation
 							return defaultGenerateId();
 						},
 					}

package/src/instrumentation/attributes.ts

@@ -0,0 +1,22 @@
+import {
+	ATTR_DB_COLLECTION_NAME,
+	ATTR_DB_OPERATION_NAME,
+	ATTR_HTTP_RESPONSE_STATUS_CODE,
+	ATTR_HTTP_ROUTE,
+} from "@opentelemetry/semantic-conventions";
+
+export {
+	ATTR_DB_COLLECTION_NAME,
+	ATTR_DB_OPERATION_NAME,
+	ATTR_HTTP_RESPONSE_STATUS_CODE,
+	ATTR_HTTP_ROUTE,
+};
+
+/** Operation identifier (e.g. getSession, signUpWithEmailAndPassword). Uses endpoint operationId when set, otherwise the endpoint key. */
+export const ATTR_OPERATION_ID = "better_auth.operation_id" as const;
+
+/** Hook type (e.g. before, after, create.before). */
+export const ATTR_HOOK_TYPE = "better_auth.hook.type" as const;
+
+/** Execution context (e.g. user, plugin:id). */
+export const ATTR_CONTEXT = "better_auth.context" as const;

package/src/instrumentation/index.ts

@@ -0,0 +1,2 @@
+export * from "./attributes";
+export * from "./tracer";