@better-auth/core 1.5.5 → 1.5.7-beta.1

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";

package/src/instrumentation/instrumentation.test.ts

@@ -0,0 +1,139 @@
+import { trace } from "@opentelemetry/api";
+import {
+	InMemorySpanExporter,
+	SimpleSpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { withSpan } from ".";
+import { ATTR_DB_COLLECTION_NAME, ATTR_DB_OPERATION_NAME } from "./attributes";
+
+describe("instrumentation", () => {
+	let provider: NodeTracerProvider;
+	let exporter: InMemorySpanExporter;
+
+	beforeAll(async () => {
+		exporter = new InMemorySpanExporter();
+		provider = new NodeTracerProvider({
+			spanProcessors: [new SimpleSpanProcessor(exporter)],
+		});
+		trace.setGlobalTracerProvider(provider);
+	});
+
+	afterAll(async () => {
+		await provider.shutdown();
+	});
+
+	beforeEach(() => {
+		exporter.reset();
+	});
+
+	it("creates a span with name and attributes for sync function", () => {
+		const result = withSpan(
+			"test.sync",
+			{
+				[ATTR_DB_OPERATION_NAME]: "findOne",
+				[ATTR_DB_COLLECTION_NAME]: "user",
+			},
+			() => 42,
+		);
+
+		expect(result).toBe(42);
+
+		const spans = exporter.getFinishedSpans();
+		expect(spans).toHaveLength(1);
+		expect(spans[0]?.name).toBe("test.sync");
+		expect(spans[0]?.attributes).toMatchObject({
+			[ATTR_DB_OPERATION_NAME]: "findOne",
+			[ATTR_DB_COLLECTION_NAME]: "user",
+		});
+	});
+
+	it("creates a span for async function", async () => {
+		const result = await withSpan(
+			"test.async",
+			{ endpoint: "getSession" },
+			async () => {
+				await new Promise((r) => setTimeout(r, 5));
+				return "session-id";
+			},
+		);
+
+		expect(result).toBe("session-id");
+
+		const spans = exporter.getFinishedSpans();
+		expect(spans).toHaveLength(1);
+		expect(spans[0]?.name).toBe("test.async");
+		expect(spans[0]?.attributes).toMatchObject({ endpoint: "getSession" });
+	});
+
+	it("records error status and exception when sync function throws", () => {
+		const err = new Error("sync failure");
+
+		expect(() =>
+			withSpan("test.sync.error", { foo: "bar" }, () => {
+				throw err;
+			}),
+		).toThrow("sync failure");
+
+		const spans = exporter.getFinishedSpans();
+		expect(spans).toHaveLength(1);
+		expect(spans[0]?.name).toBe("test.sync.error");
+		expect(spans[0]?.status).toMatchObject({
+			code: 2,
+			message: "sync failure",
+		});
+	});
+
+	it("records error status and exception when async function rejects", async () => {
+		const err = new Error("async failure");
+
+		await expect(
+			withSpan("test.async.error", { baz: 1 }, async () => {
+				await Promise.resolve();
+				throw err;
+			}),
+		).rejects.toThrow("async failure");
+
+		const spans = exporter.getFinishedSpans();
+		expect(spans).toHaveLength(1);
+		expect(spans[0]?.name).toBe("test.async.error");
+		expect(spans[0]?.status).toMatchObject({
+			code: 2,
+			message: "async failure",
+		});
+	});
+
+	it("creates multiple sequential spans", () => {
+		void withSpan("first", { order: 1 }, () => 1);
+		void withSpan("second", { order: 2 }, () => 2);
+
+		const spans = exporter.getFinishedSpans();
+		expect(spans).toHaveLength(2);
+		expect(spans.map((s) => s.name)).toEqual(
+			expect.arrayContaining(["first", "second"]),
+		);
+	});
+
+	it("creates nested spans when withSpan is composed", () => {
+		const result = withSpan("outer", { depth: 0 }, () => {
+			return withSpan("inner", { depth: 1 }, () => "ok");
+		});
+
+		expect(result).toBe("ok");
+
+		const spans = exporter.getFinishedSpans();
+		expect(spans).toHaveLength(2);
+		expect(spans.map((s) => s.name).sort()).toEqual(["inner", "outer"]);
+	});
+
+	it("uses better-auth instrumentation scope", () => {
+		void withSpan("scope.check", {}, () => undefined);
+
+		const spans = exporter.getFinishedSpans();
+		expect(spans).toHaveLength(1);
+
+		const span = spans[0];
+		expect(span?.instrumentationLibrary?.name).toBe("better-auth");
+	});
+});