@better-auth/core 1.4.6-beta.2 → 1.4.6-beta.4

package/src/db/adapter/get-default-field-name.ts

@@ -0,0 +1,59 @@
+import { BetterAuthError } from "../../error";
+import type { BetterAuthDBSchema } from "../type";
+import { initGetDefaultModelName } from "./get-default-model-name";
+
+export const initGetDefaultFieldName = ({
+	schema,
+	usePlural,
+}: {
+	schema: BetterAuthDBSchema;
+	usePlural: boolean | undefined;
+}) => {
+	const getDefaultModelName = initGetDefaultModelName({
+		schema,
+		usePlural,
+	});
+
+	/**
+	 * This function helps us get the default field name from the schema defined by devs.
+	 * Often times, the user will be using the `fieldName` which could had been customized by the users.
+	 * This function helps us get the actual field name useful to match against the schema. (eg: schema[model].fields[field])
+	 *
+	 * If it's still unclear what this does:
+	 *
+	 * 1. User can define a custom fieldName.
+	 * 2. When using a custom fieldName, doing something like `schema[model].fields[field]` will not work.
+	 */
+	const getDefaultFieldName = ({
+		field,
+		model: unsafeModel,
+	}: {
+		model: string;
+		field: string;
+	}) => {
+		// Plugin `schema`s can't define their own `id`. Better-auth auto provides `id` to every schema model.
+		// Given this, we can't just check if the `field` (that being `id`) is within the schema's fields, since it is never defined.
+		// So we check if the `field` is `id` and if so, we return `id` itself. Otherwise, we return the `field` from the schema.
+		if (field === "id" || field === "_id") {
+			return "id";
+		}
+		const model = getDefaultModelName(unsafeModel); // Just to make sure the model name is correct.
+
+		let f = schema[model]?.fields[field];
+		if (!f) {
+			const result = Object.entries(schema[model]!.fields!).find(
+				([_, f]) => f.fieldName === field,
+			);
+			if (result) {
+				f = result[1];
+				field = result[0];
+			}
+		}
+		if (!f) {
+			throw new BetterAuthError(`Field ${field} not found in model ${model}`);
+		}
+		return field;
+	};
+
+	return getDefaultFieldName;
+};

package/src/db/adapter/get-default-model-name.ts

@@ -0,0 +1,51 @@
+import { BetterAuthError } from "../../error";
+import type { BetterAuthDBSchema } from "../type";
+
+export const initGetDefaultModelName = ({
+	usePlural,
+	schema,
+}: {
+	usePlural: boolean | undefined;
+	schema: BetterAuthDBSchema;
+}) => {
+	/**
+	 * This function helps us get the default model name from the schema defined by devs.
+	 * Often times, the user will be using the `modelName` which could had been customized by the users.
+	 * This function helps us get the actual model name useful to match against the schema. (eg: schema[model])
+	 *
+	 * If it's still unclear what this does:
+	 *
+	 * 1. User can define a custom modelName.
+	 * 2. When using a custom modelName, doing something like `schema[model]` will not work.
+	 * 3. Using this function helps us get the actual model name based on the user's defined custom modelName.
+	 */
+	const getDefaultModelName = (model: string) => {
+		// It's possible this `model` could had applied `usePlural`.
+		// Thus we'll try the search but without the trailing `s`.
+		if (usePlural && model.charAt(model.length - 1) === "s") {
+			let pluralessModel = model.slice(0, -1);
+			let m = schema[pluralessModel] ? pluralessModel : undefined;
+			if (!m) {
+				m = Object.entries(schema).find(
+					([_, f]) => f.modelName === pluralessModel,
+				)?.[0];
+			}
+
+			if (m) {
+				return m;
+			}
+		}
+
+		let m = schema[model] ? model : undefined;
+		if (!m) {
+			m = Object.entries(schema).find(([_, f]) => f.modelName === model)?.[0];
+		}
+
+		if (!m) {
+			throw new BetterAuthError(`Model "${model}" not found in schema`);
+		}
+		return m;
+	};
+
+	return getDefaultModelName;
+};

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

@@ -0,0 +1,62 @@
+import { BetterAuthError } from "../../error";
+import type { BetterAuthOptions } from "../../types";
+import type { BetterAuthDBSchema } from "../type";
+import { initGetDefaultFieldName } from "./get-default-field-name";
+import { initGetDefaultModelName } from "./get-default-model-name";
+import { initGetIdField } from "./get-id-field";
+
+export const initGetFieldAttributes = ({
+	usePlural,
+	schema,
+	options,
+	customIdGenerator,
+	disableIdGeneration,
+}: {
+	usePlural?: boolean;
+	schema: BetterAuthDBSchema;
+	options: BetterAuthOptions;
+	disableIdGeneration?: boolean;
+	customIdGenerator?: ((props: { model: string }) => string) | undefined;
+}) => {
+	const getDefaultModelName = initGetDefaultModelName({
+		usePlural,
+		schema,
+	});
+
+	const getDefaultFieldName = initGetDefaultFieldName({
+		usePlural,
+		schema,
+	});
+
+	const idField = initGetIdField({
+		usePlural,
+		schema,
+		options,
+		customIdGenerator,
+		disableIdGeneration,
+	});
+
+	const getFieldAttributes = ({
+		model,
+		field,
+	}: {
+		model: string;
+		field: string;
+	}) => {
+		const defaultModelName = getDefaultModelName(model);
+		const defaultFieldName = getDefaultFieldName({
+			field: field,
+			model: defaultModelName,
+		});
+
+		const fields = schema[defaultModelName]!.fields;
+		fields.id = idField({ customModelName: defaultModelName });
+		const fieldAttributes = fields[defaultFieldName];
+		if (!fieldAttributes) {
+			throw new BetterAuthError(`Field ${field} not found in model ${model}`);
+		}
+		return fieldAttributes;
+	};
+
+	return getFieldAttributes;
+};

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

@@ -0,0 +1,43 @@
+import type { BetterAuthDBSchema } from "../type";
+import { initGetDefaultFieldName } from "./get-default-field-name";
+import { initGetDefaultModelName } from "./get-default-model-name";
+
+export const initGetFieldName = ({
+	schema,
+	usePlural,
+}: {
+	schema: BetterAuthDBSchema;
+	usePlural: boolean | undefined;
+}) => {
+	const getDefaultModelName = initGetDefaultModelName({
+		schema,
+		usePlural,
+	});
+
+	const getDefaultFieldName = initGetDefaultFieldName({
+		schema,
+		usePlural,
+	});
+
+	/**
+	 * Get the field name which is expected to be saved in the database based on the user's schema.
+	 *
+	 * This function is useful if you need to save the field name to the database.
+	 *
+	 * For example, if the user has defined a custom field name for the `user` model, then you can use this function to get the actual field name from the schema.
+	 */
+	function getFieldName({
+		model: modelName,
+		field: fieldName,
+	}: {
+		model: string;
+		field: string;
+	}) {
+		const model = getDefaultModelName(modelName);
+		const field = getDefaultFieldName({ model, field: fieldName });
+
+		return schema[model]?.fields[field]?.fieldName || field;
+	}
+
+	return getFieldName;
+};

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

@@ -0,0 +1,141 @@
+import { logger } from "../../env";
+import type { BetterAuthOptions } from "../../types";
+import { generateId as defaultGenerateId } from "../../utils";
+import type { BetterAuthDBSchema, DBFieldAttribute } from "../type";
+import { initGetDefaultModelName } from "./get-default-model-name";
+
+export const initGetIdField = ({
+	usePlural,
+	schema,
+	disableIdGeneration,
+	options,
+	customIdGenerator,
+	supportsUUIDs,
+}: {
+	usePlural?: boolean;
+	schema: BetterAuthDBSchema;
+	options: BetterAuthOptions;
+	disableIdGeneration?: boolean;
+	customIdGenerator?: ((props: { model: string }) => string) | undefined;
+	supportsUUIDs?: boolean;
+}) => {
+	const getDefaultModelName = initGetDefaultModelName({
+		usePlural: usePlural,
+		schema,
+	});
+
+	const idField = ({
+		customModelName,
+		forceAllowId,
+	}: {
+		customModelName?: string;
+		forceAllowId?: boolean;
+	}) => {
+		const useNumberId =
+			options.advanced?.database?.useNumberId ||
+			options.advanced?.database?.generateId === "serial";
+		const useUUIDs = options.advanced?.database?.generateId === "uuid";
+
+		let shouldGenerateId: boolean = (() => {
+			if (disableIdGeneration) {
+				return false;
+			} else if (useNumberId && !forceAllowId) {
+				// if force allow is true, then we should be using their custom provided id.
+				return false;
+			} else if (useUUIDs) {
+				// should only generate UUIDs via JS if the database doesn't support natively generating UUIDs.
+				return !supportsUUIDs;
+			} else {
+				return true;
+			}
+		})();
+
+		const model = getDefaultModelName(customModelName ?? "id");
+		return {
+			type: useNumberId ? "number" : "string",
+			required: shouldGenerateId ? true : false,
+			...(shouldGenerateId
+				? {
+						defaultValue() {
+							if (disableIdGeneration) return undefined;
+							let generateId = options.advanced?.database?.generateId;
+							if (generateId === false || useNumberId) return undefined;
+							if (typeof generateId === "function") {
+								return generateId({
+									model,
+								});
+							}
+							if (customIdGenerator) {
+								return customIdGenerator({ model });
+							}
+							if (generateId === "uuid") {
+								return crypto.randomUUID();
+							}
+							return defaultGenerateId();
+						},
+					}
+				: {}),
+			transform: {
+				input: (value) => {
+					// Uncomment if need to debug id transformation
+					// console.log(`transforming id: `, {
+					// 	id: value,
+					// 	...(useNumberId ? { useNumberId } : {}),
+					// 	...(useUUIDs ? { useUUIDs } : {}),
+					// 	...(forceAllowId ? { forceAllowId } : {}),
+					// });
+					if (!value) return undefined;
+
+					if (useNumberId) {
+						const numberValue = Number(value);
+						// if invalid number, fallback to DB generated number id.
+						if (isNaN(numberValue)) {
+							return undefined;
+						}
+						return numberValue;
+					}
+
+					if (useUUIDs) {
+						// if it's generated by us, then we should return the value as is.
+						if (shouldGenerateId && !forceAllowId) return value;
+						if (disableIdGeneration) return undefined;
+						// if DB will handle UUID generation, then we should return undefined.
+						if (supportsUUIDs) return undefined;
+						// if forceAllowId is true, it means we should be using the ID provided during the adapter call.
+						if (forceAllowId && typeof value === "string") {
+							const uuidRegex =
+								/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+							if (uuidRegex.test(value)) {
+								return value;
+							} else {
+								const err = new Error();
+								const stack = err.stack
+									?.split("\n")
+									.filter((_, i) => i !== 1)
+									.join("\n")
+									.replace("Error:", "");
+								logger.warn(
+									"[Adapter Factory] - Invalid UUID value for field `id` provided when `forceAllowId` is true. Generating a new UUID.",
+									stack,
+								);
+							}
+						}
+						// if the value is not a string, and the database doesn't support generating it's own UUIDs, then we should be generating the UUID.
+						if (typeof value !== "string" && !supportsUUIDs) {
+							return crypto.randomUUID();
+						}
+						return undefined;
+					}
+
+					return value;
+				},
+				output: (value) => {
+					if (!value) return undefined;
+					return String(value);
+				},
+			},
+		} satisfies DBFieldAttribute;
+	};
+
+	return idField;
+};

package/src/db/adapter/get-model-name.ts

@@ -0,0 +1,36 @@
+import type { BetterAuthDBSchema } from "../type";
+import { initGetDefaultModelName } from "./get-default-model-name";
+
+export const initGetModelName = ({
+	usePlural,
+	schema,
+}: {
+	usePlural: boolean | undefined;
+	schema: BetterAuthDBSchema;
+}) => {
+	const getDefaultModelName = initGetDefaultModelName({
+		schema,
+		usePlural,
+	});
+	/**
+	 * Users can overwrite the default model of some tables. This function helps find the correct model name.
+	 * Furthermore, if the user passes `usePlural` as true in their adapter config,
+	 * then we should return the model name ending with an `s`.
+	 */
+	const getModelName = (model: string) => {
+		const defaultModelKey = getDefaultModelName(model);
+		const useCustomModelName =
+			schema &&
+			schema[defaultModelKey] &&
+			schema[defaultModelKey].modelName !== model;
+
+		if (useCustomModelName) {
+			return usePlural
+				? `${schema[defaultModelKey]!.modelName}s`
+				: schema[defaultModelKey]!.modelName;
+		}
+
+		return usePlural ? `${model}s` : model;
+	};
+	return getModelName;
+};

package/src/db/adapter/index.ts

@@ -112,6 +112,14 @@ export interface DBAdapterFactoryConfig<
 	 * @default true
 	 */
 	supportsBooleans?: boolean | undefined;
+	/**
+	 * If the database doesn't support arrays, set this to `false`.
+	 *
+	 * We will handle the translation between using `array`s, and saving `string`s to the database.
+	 *
+	 * @default false
+	 */
+	supportsArrays?: boolean | undefined;
 	/**
 	 * Execute multiple operations in a transaction.
 	 *
@@ -532,3 +540,7 @@ export interface DBAdapterInstance<
 > {
 	(options: BetterAuthOptions): DBAdapter<Options>;
 }
+
+export * from "./factory";
+export * from "./types";
+export * from "./utils";

package/src/db/adapter/types.ts

@@ -0,0 +1,161 @@
+import type { BetterAuthOptions } from "../../types";
+import type { Prettify } from "../../types/helper";
+import type { BetterAuthDBSchema, DBFieldAttribute } from "../type";
+import type {
+	DBAdapterSchemaCreation as AdapterSchemaCreation,
+	CustomAdapter as CoreCustomAdapter,
+	DBAdapterFactoryConfig,
+	JoinConfig,
+	DBTransactionAdapter as TransactionAdapter,
+	Where,
+} from "./index";
+
+export type AdapterFactoryOptions = {
+	config: AdapterFactoryConfig;
+	adapter: AdapterFactoryCustomizeAdapterCreator;
+};
+
+export interface AdapterFactoryConfig
+	extends Omit<DBAdapterFactoryConfig<BetterAuthOptions>, "transaction"> {
+	/**
+	 * Execute multiple operations in a transaction.
+	 *
+	 * If the database doesn't support transactions, set this to `false` and operations will be executed sequentially.
+	 *
+	 * @default false
+	 */
+	transaction?:
+		| (
+				| false
+				| (<R>(callback: (trx: TransactionAdapter) => Promise<R>) => Promise<R>)
+		  )
+		| undefined;
+}
+
+export type AdapterFactoryCustomizeAdapterCreator = (config: {
+	options: BetterAuthOptions;
+	/**
+	 * The schema of the user's Better-Auth instance.
+	 */
+	schema: BetterAuthDBSchema;
+	/**
+	 * The debug log function.
+	 *
+	 * If the config has defined `debugLogs` as `false`, no logs will be shown.
+	 */
+	debugLog: (...args: any[]) => void;
+	/**
+	 * Get the model name which is expected to be saved in the database based on the user's schema.
+	 */
+	getModelName: (model: string) => string;
+	/**
+	 * Get the field name which is expected to be saved in the database based on the user's schema.
+	 */
+	getFieldName: ({ model, field }: { model: string; field: string }) => string;
+	/**
+	 * This function helps us get the default model name from the schema defined by devs.
+	 * Often times, the user will be using the `modelName` which could had been customized by the users.
+	 * This function helps us get the actual model name useful to match against the schema. (eg: schema[model])
+	 *
+	 * If it's still unclear what this does:
+	 *
+	 * 1. User can define a custom modelName.
+	 * 2. When using a custom modelName, doing something like `schema[model]` will not work.
+	 * 3. Using this function helps us get the actual model name based on the user's defined custom modelName.
+	 * 4. Thus allowing us to use `schema[model]`.
+	 */
+	getDefaultModelName: (model: string) => string;
+	/**
+	 * This function helps us get the default field name from the schema defined by devs.
+	 * Often times, the user will be using the `fieldName` which could had been customized by the users.
+	 * This function helps us get the actual field name useful to match against the schema. (eg: schema[model].fields[field])
+	 *
+	 * If it's still unclear what this does:
+	 *
+	 * 1. User can define a custom fieldName.
+	 * 2. When using a custom fieldName, doing something like `schema[model].fields[field]` will not work.
+	 *
+	 */
+	getDefaultFieldName: ({
+		model,
+		field,
+	}: {
+		model: string;
+		field: string;
+	}) => string;
+	/**
+	 * Get the field attributes for a given model and field.
+	 *
+	 * Note: any model name or field name is allowed, whether default to schema or not.
+	 */
+	getFieldAttributes: ({
+		model,
+		field,
+	}: {
+		model: string;
+		field: string;
+	}) => DBFieldAttribute;
+	// The following functions are exposed primarily for the purpose of having wrapper adapters.
+	transformInput: (
+		data: Record<string, any>,
+		defaultModelName: string,
+		action: "create" | "update",
+		forceAllowId?: boolean | undefined,
+	) => Promise<Record<string, any>>;
+	transformOutput: (
+		data: Record<string, any>,
+		defaultModelName: string,
+		select?: string[] | undefined,
+		joinConfig?: JoinConfig | undefined,
+	) => Promise<Record<string, any>>;
+	transformWhereClause: <W extends Where[] | undefined>({
+		model,
+		where,
+	}: {
+		where: W;
+		model: string;
+	}) => W extends undefined ? undefined : CleanedWhere[];
+}) => CustomAdapter;
+
+/**
+ * @deprecated Use `CustomAdapter` from `@better-auth/core/db/adapter` instead.
+ */
+export interface CustomAdapter extends Omit<CoreCustomAdapter, "createSchema"> {
+	createSchema?:
+		| ((props: {
+				/**
+				 * The file the user may have passed in to the `generate` command as the expected schema file output path.
+				 */
+				file?: string;
+				/**
+				 * The tables from the user's Better-Auth instance schema.
+				 */
+				tables: BetterAuthDBSchema;
+		  }) => Promise<AdapterSchemaCreation>)
+		| undefined;
+}
+
+/**
+ * @deprecated Use `CleanedWhere` from `@better-auth/core/db/adapter` instead.
+ */
+export type CleanedWhere = Prettify<Required<Where>>;
+
+export type AdapterTestDebugLogs = {
+	resetDebugLogs: () => void;
+	printDebugLogs: () => void;
+};
+
+/**
+ * @deprecated Use `AdapterFactoryOptions` instead. This export will be removed in a future version.
+ */
+export type CreateAdapterOptions = AdapterFactoryOptions;
+
+/**
+ * @deprecated Use `AdapterFactoryConfig` instead. This export will be removed in a future version.
+ */
+export type AdapterConfig = AdapterFactoryConfig;
+
+/**
+ * @deprecated Use `AdapterFactoryCustomizeAdapterCreator` instead. This export will be removed in a future version.
+ */
+export type CreateCustomAdapter = AdapterFactoryCustomizeAdapterCreator;

package/src/db/adapter/utils.ts

@@ -0,0 +1,61 @@
+import type { DBFieldAttribute } from "../type";
+
+export function withApplyDefault(
+	value: any,
+	field: DBFieldAttribute,
+	action: "create" | "update" | "findOne" | "findMany",
+) {
+	if (action === "update") {
+		// Apply onUpdate if value is undefined
+		if (value === undefined && field.onUpdate !== undefined) {
+			if (typeof field.onUpdate === "function") {
+				return field.onUpdate();
+			}
+			return field.onUpdate;
+		}
+		return value;
+	}
+	if (action === "create") {
+		// we do not want to apply default values if the value is null & not required
+		if (value === undefined || (field.required === true && value === null)) {
+			if (field.defaultValue !== undefined) {
+				if (typeof field.defaultValue === "function") {
+					return field.defaultValue();
+				}
+				return field.defaultValue;
+			}
+		}
+	}
+	return value;
+}
+
+function isObject(item: unknown): item is Record<string, unknown> {
+	return item !== null && typeof item === "object" && !Array.isArray(item);
+}
+
+export function deepmerge<T>(target: T, source: Partial<T>): T {
+	if (Array.isArray(target) && Array.isArray(source)) {
+		// merge arrays by concatenation
+		return [...target, ...source] as T;
+	} else if (isObject(target) && isObject(source)) {
+		const result: Record<string, unknown> = { ...target };
+
+		for (const [key, value] of Object.entries(source)) {
+			if (value === undefined) continue; // skip undefined
+
+			if (key in target) {
+				result[key] = deepmerge(
+					(target as Record<string, unknown>)[key],
+					value as unknown as Partial<T>,
+				);
+			} else {
+				result[key] = value;
+			}
+		}
+
+		return result as T;
+	}
+
+	// primitives and fallback: source overrides target
+	return source as T;
+}