better-auth-firestore 1.1.4 → 1.2.1

package/README.md

@@ -448,6 +448,24 @@ const url = generateIndexSetupUrl(process.env.FIREBASE_PROJECT_ID!);
 console.log(url); // Open this URL to create the index
 ```
 
+## FAQ
+
+### Can I migrate from Auth.js / NextAuth without changing existing Firestore data?
+
+Yes. `better-auth-firestore` is designed as a drop-in replacement for the Auth.js Firebase adapter with matching collection names and field shapes by default, so most projects do not need a Firestore data migration. See [Migration from Auth.js/NextAuth](#migration-from-authjsnextauth) for the adapter-specific details.
+
+### What's the difference between `better-auth-firestore` and `better-auth-firebase-auth`?
+
+`better-auth-firestore` is a database adapter for storing Better Auth users, sessions, accounts, and verification tokens in Firestore through the Firebase Admin SDK. `better-auth-firebase-auth` is for Firebase Authentication provider integration such as Email/Password, Google sign-in, client/server token generation, and password reset flows. Use the Firestore adapter for data storage and the Firebase Auth plugin when you need Firebase Authentication features.
+
+### Which runtimes are supported?
+
+This package supports server-side Node.js runtimes, including Next.js route handlers, Cloud Functions, and Cloud Run, anywhere the Firebase Admin SDK is supported. Edge runtimes such as Vercel Edge Functions and Cloudflare Workers are not supported because the Firestore Admin SDK does not run there. See [Runtime compatibility](#runtime-compatibility) for the current matrix.
+
+### Why is a Firestore composite index required for verification tokens?
+
+Better Auth verification token lookups require a Firestore query pattern that depends on a composite index. Without that index, verification-related queries can fail with a missing index error or insufficient permissions message. See [Create Required Firestore Index](#3-create-required-firestore-index) for the exact fields and setup options.
+
 ## Related Links
 
 - [Better Auth Documentation](https://www.better-auth.com/docs)

package/dist/firebase-adapter.js

@@ -9,14 +9,60 @@ const MAP_TO_FIRESTORE = {
 };
 const MAP_FROM_FIRESTORE = Object.fromEntries(Object.entries(MAP_TO_FIRESTORE).map(([k, v]) => [v, k]));
 const identity = (x) => x;
+const DB_TO_CANONICAL_FIELD = {
+    user_id: "userId",
+    session_token: "sessionToken",
+    provider_account_id: "providerAccountId",
+    email_verified: "emailVerified",
+};
+function canonicalizeFieldName(field) {
+    return DB_TO_CANONICAL_FIELD[field] ?? field;
+}
 function mapFieldsFactory(preferSnakeCase) {
     if (preferSnakeCase) {
         return {
-            toDb: (field) => MAP_TO_FIRESTORE[field] ?? field,
+            toDb: (field) => {
+                const canonical = canonicalizeFieldName(field);
+                return MAP_TO_FIRESTORE[canonical] ?? canonical;
+            },
             fromDb: (field) => MAP_FROM_FIRESTORE[field] ?? field,
         };
     }
-    return { toDb: identity, fromDb: identity };
+    return {
+        toDb: (field) => canonicalizeFieldName(field),
+        fromDb: (field) => MAP_FROM_FIRESTORE[field] ?? field,
+    };
+}
+/**
+ * Firestore caps the `IN` operator at 30 comparison values. When a `where`
+ * clause passes more than this, queries throw with
+ * `INVALID_ARGUMENT: 'IN' supports up to 30 comparison values.`
+ * We split oversized IN values into chunks of this size in both `deleteMany`
+ * and the regular `findMany` path and merge results.
+ * https://firebase.google.com/docs/firestore/query-data/queries#query_limitations
+ */
+const FIRESTORE_IN_CHUNK_SIZE = 30;
+/**
+ * Narrows a where clause to an `in` condition whose value array exceeds
+ * Firestore's 30-value cap. Used by query methods to trigger chunked
+ * sub-queries.
+ */
+function findOversizedInClause(where) {
+    return (where ?? []).find((w) => w.operator === "in" &&
+        Array.isArray(w.value) &&
+        w.value.length > FIRESTORE_IN_CHUNK_SIZE);
+}
+function getChunkedWhereClauses(where) {
+    const oversized = findOversizedInClause(where);
+    if (!oversized || !where) {
+        return [where];
+    }
+    const chunkedClauses = [];
+    for (let i = 0; i < oversized.value.length; i += FIRESTORE_IN_CHUNK_SIZE) {
+        const chunk = oversized.value.slice(i, i + FIRESTORE_IN_CHUNK_SIZE);
+        chunkedClauses.push(where.map((w) => w === oversized ? { ...w, value: chunk } : w));
+    }
+    return chunkedClauses;
 }
 function resolveDb(config) {
     if (!config)
@@ -139,6 +185,36 @@ function applyOperator(query, field, operator, value) {
             return query.where(field, "==", value);
     }
 }
+function isDocumentReferenceLike(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "id" in value &&
+        typeof value.id === "string" &&
+        "path" in value &&
+        typeof value.path === "string");
+}
+function normalizeSessionWriteData(data) {
+    const { user_id, session_token, ...rest } = data;
+    const normalized = { ...rest };
+    const userIdValue = normalized.userId ?? user_id;
+    if (typeof userIdValue === "string") {
+        normalized.userId = userIdValue;
+    }
+    else if (isDocumentReferenceLike(userIdValue)) {
+        normalized.userId = userIdValue.id;
+    }
+    const sessionTokenValue = normalized.sessionToken ?? session_token;
+    if (typeof sessionTokenValue === "string") {
+        normalized.sessionToken = sessionTokenValue;
+    }
+    return normalized;
+}
+function normalizeWriteData(model, data) {
+    const normalizedModel = model.toLowerCase().replace(/s$/, "");
+    if (normalizedModel !== "session")
+        return data;
+    return normalizeSessionWriteData(data);
+}
 export const firestoreAdapter = (config = {}) => {
     const db = resolveDb(config);
     const { namingStrategy = "default", collections: collectionsOverride = {}, debugLogs = false, } = (config && config.collection
@@ -162,8 +238,9 @@ export const firestoreAdapter = (config = {}) => {
                         create: async ({ model, data }) => {
                             const col = getCollectionRef(db, model, collections);
                             let ref = col.doc();
+                            const normalizedData = normalizeWriteData(model, data);
                             const docData = {};
-                            for (const [k, v] of Object.entries(data)) {
+                            for (const [k, v] of Object.entries(normalizedData)) {
                                 if (k === "id" && v) {
                                     ref = col.doc(v);
                                     continue;
@@ -171,17 +248,23 @@ export const firestoreAdapter = (config = {}) => {
                                 docData[mapper.toDb(k)] = v;
                             }
                             transaction.set(ref, docData);
-                            return { ...data, id: ref.id };
+                            return { ...normalizedData, id: ref.id };
                         },
                         update: async ({ model, where, update }) => {
                             const col = getCollectionRef(db, model, collections);
-                            const q = applyWhereClause(col, where, mapper);
-                            const snap = await transaction.get(q.limit(1));
-                            const doc = snap.docs[0];
+                            let doc;
+                            for (const whereClause of getChunkedWhereClauses(where)) {
+                                const q = applyWhereClause(col, whereClause, mapper);
+                                const snap = await transaction.get(q.limit(1));
+                                doc = snap.docs[0];
+                                if (doc)
+                                    break;
+                            }
                             if (!doc)
                                 return null;
+                            const normalizedUpdate = normalizeWriteData(model, update);
                             const updateData = {};
-                            for (const [k, v] of Object.entries(update)) {
+                            for (const [k, v] of Object.entries(normalizedUpdate)) {
                                 updateData[mapper.toDb(k)] = v;
                             }
                             transaction.update(doc.ref, updateData);
@@ -192,13 +275,18 @@ export const firestoreAdapter = (config = {}) => {
                                     result[mapper.fromDb(k)] = v;
                                 }
                             }
-                            return { ...result, ...update };
+                            return { ...result, ...normalizedUpdate };
                         },
                         findOne: async ({ model, where }) => {
                             const col = getCollectionRef(db, model, collections);
-                            const q = applyWhereClause(col, where, mapper);
-                            const snap = await transaction.get(q.limit(1));
-                            const doc = snap.docs[0];
+                            let doc;
+                            for (const whereClause of getChunkedWhereClauses(where)) {
+                                const q = applyWhereClause(col, whereClause, mapper);
+                                const snap = await transaction.get(q.limit(1));
+                                doc = snap.docs[0];
+                                if (doc)
+                                    break;
+                            }
                             if (!doc)
                                 return null;
                             const data = doc.data();
@@ -220,8 +308,9 @@ export const firestoreAdapter = (config = {}) => {
                 create: async ({ model, data }) => {
                     const col = getCollectionRef(db, model, collections);
                     let ref = col.doc();
+                    const normalizedData = normalizeWriteData(model, data);
                     const docData = {};
-                    for (const [k, v] of Object.entries(data)) {
+                    for (const [k, v] of Object.entries(normalizedData)) {
                         if (k === "id" && v) {
                             ref = col.doc(v);
                             continue;
@@ -259,14 +348,15 @@ export const firestoreAdapter = (config = {}) => {
                     }
                     if (debugLogs) {
                         console.log(`[Firestore Adapter] CREATE ${model} - returning:`, {
-                            ...data,
+                            ...normalizedData,
                             ...result,
                         });
                     }
-                    return { ...data, ...result };
+                    return { ...normalizedData, ...result };
                 },
                 update: async ({ model, where, update }) => {
                     const col = getCollectionRef(db, model, collections);
+                    const normalizedUpdate = normalizeWriteData(model, update);
                     // Special case: if where clause is just "id eq value", use doc() instead of query
                     if (where &&
                         where.length === 1 &&
@@ -289,7 +379,7 @@ export const firestoreAdapter = (config = {}) => {
                             return null;
                         }
                         const updateData = {};
-                        for (const [k, v] of Object.entries(update)) {
+                        for (const [k, v] of Object.entries(normalizedUpdate)) {
                             updateData[mapper.toDb(k)] = v;
                         }
                         if (debugLogs) {
@@ -310,7 +400,6 @@ export const firestoreAdapter = (config = {}) => {
                         }
                         return result;
                     }
-                    const q = applyWhereClause(col, where, mapper);
                     if (debugLogs) {
                         console.log(`[Firestore Adapter] UPDATE ${model}:`, {
                             where,
@@ -318,8 +407,14 @@ export const firestoreAdapter = (config = {}) => {
                             collection: collections,
                         });
                     }
-                    const snap = await q.limit(1).get();
-                    const doc = snap.docs[0];
+                    let doc;
+                    for (const whereClause of getChunkedWhereClauses(where)) {
+                        const q = applyWhereClause(col, whereClause, mapper);
+                        const snap = await q.limit(1).get();
+                        doc = snap.docs[0];
+                        if (doc)
+                            break;
+                    }
                     if (!doc) {
                         if (debugLogs) {
                             console.log(`[Firestore Adapter] UPDATE ${model} - no document found`);
@@ -327,7 +422,7 @@ export const firestoreAdapter = (config = {}) => {
                         return null;
                     }
                     const updateData = {};
-                    for (const [k, v] of Object.entries(update)) {
+                    for (const [k, v] of Object.entries(normalizedUpdate)) {
                         updateData[mapper.toDb(k)] = v;
                     }
                     if (debugLogs) {
@@ -350,16 +445,23 @@ export const firestoreAdapter = (config = {}) => {
                 },
                 updateMany: async ({ model, where, update }) => {
                     const col = getCollectionRef(db, model, collections);
-                    const q = applyWhereClause(col, where, mapper);
-                    const snap = await q.get();
                     let count = 0;
+                    const seenDocIds = new Set();
+                    const normalizedUpdate = normalizeWriteData(model, update);
                     const updateData = {};
-                    for (const [k, v] of Object.entries(update)) {
+                    for (const [k, v] of Object.entries(normalizedUpdate)) {
                         updateData[mapper.toDb(k)] = v;
                     }
-                    for (const d of snap.docs) {
-                        await d.ref.update(updateData);
-                        count++;
+                    for (const whereClause of getChunkedWhereClauses(where)) {
+                        const q = applyWhereClause(col, whereClause, mapper);
+                        const snap = await q.get();
+                        for (const d of snap.docs) {
+                            if (seenDocIds.has(d.id))
+                                continue;
+                            seenDocIds.add(d.id);
+                            await d.ref.update(updateData);
+                            count++;
+                        }
                     }
                     return count;
                 },
@@ -384,14 +486,40 @@ export const firestoreAdapter = (config = {}) => {
                         }
                         return;
                     }
-                    const q = applyWhereClause(col, where, mapper);
-                    const snap = await q.limit(1).get();
-                    const doc = snap.docs[0];
+                    let doc;
+                    for (const whereClause of getChunkedWhereClauses(where)) {
+                        const q = applyWhereClause(col, whereClause, mapper);
+                        const snap = await q.limit(1).get();
+                        doc = snap.docs[0];
+                        if (doc)
+                            break;
+                    }
                     if (doc)
                         await doc.ref.delete();
                 },
                 deleteMany: async ({ model, where }) => {
                     const col = getCollectionRef(db, model, collections);
+                    // Firestore's `IN` operator caps at 30 values. If a single where
+                    // clause carries more than 30 values, split into sub-queries and
+                    // sum the deletes so callers (e.g. better-auth's multi-session
+                    // `deleteSessions(tokens)`) don't blow up once they cross the cap.
+                    const oversized = findOversizedInClause(where);
+                    if (oversized) {
+                        let total = 0;
+                        for (let i = 0; i < oversized.value.length; i += FIRESTORE_IN_CHUNK_SIZE) {
+                            const chunk = oversized.value.slice(i, i + FIRESTORE_IN_CHUNK_SIZE);
+                            const chunkedWhere = where.map((w) => w === oversized
+                                ? { ...w, value: chunk }
+                                : w);
+                            const cq = applyWhereClause(col, chunkedWhere, mapper);
+                            const csnap = await cq.get();
+                            for (const d of csnap.docs) {
+                                await d.ref.delete();
+                                total++;
+                            }
+                        }
+                        return total;
+                    }
                     const q = applyWhereClause(col, where, mapper);
                     const snap = await q.get();
                     let count = 0;
@@ -472,7 +600,6 @@ export const firestoreAdapter = (config = {}) => {
                         }
                         return result;
                     }
-                    const q = applyWhereClause(col, where, mapper);
                     if (debugLogs) {
                         console.log(`[Firestore Adapter] FINDONE ${model}:`, {
                             where,
@@ -480,11 +607,21 @@ export const firestoreAdapter = (config = {}) => {
                             collection: collections,
                         });
                     }
-                    const snap = await q.limit(1).get();
+                    let snapshotSize = 0;
+                    let snapshotDocsLength = 0;
+                    let doc;
+                    for (const whereClause of getChunkedWhereClauses(where)) {
+                        const q = applyWhereClause(col, whereClause, mapper);
+                        const snap = await q.limit(1).get();
+                        snapshotSize = snap.size;
+                        snapshotDocsLength = snap.docs.length;
+                        doc = snap.docs[0];
+                        if (doc)
+                            break;
+                    }
                     if (debugLogs) {
-                        console.log(`[Firestore Adapter] FINDONE ${model} - snapshot size:`, snap.size, "docs:", snap.docs.length);
+                        console.log(`[Firestore Adapter] FINDONE ${model} - snapshot size:`, snapshotSize, "docs:", snapshotDocsLength);
                     }
-                    const doc = snap.docs[0];
                     if (!doc || !doc.exists) {
                         if (debugLogs) {
                             console.log(`[Firestore Adapter] FINDONE ${model} - no document found`);
@@ -772,6 +909,54 @@ export const firestoreAdapter = (config = {}) => {
                             results = results.slice(0, limit);
                         return results;
                     }
+                    // Firestore's `IN` operator caps at 30 values. If a simple non-ID
+                    // `in` query carries more than 30 values, split into chunks and
+                    // merge the results. Any post-filter sort / offset / limit is
+                    // re-applied after the merge to preserve the caller-visible
+                    // ordering and pagination.
+                    const oversizedIn = findOversizedInClause(where);
+                    if (oversizedIn) {
+                        const merged = new Map();
+                        for (let i = 0; i < oversizedIn.value.length; i += FIRESTORE_IN_CHUNK_SIZE) {
+                            const chunk = oversizedIn.value.slice(i, i + FIRESTORE_IN_CHUNK_SIZE);
+                            const chunkedWhere = where.map((w) => w === oversizedIn
+                                ? { ...w, value: chunk }
+                                : w);
+                            let cq = applyWhereClause(col, chunkedWhere, mapper);
+                            if (sortBy?.field) {
+                                const fieldName = mapper.toDb(sortBy.field);
+                                const direction = sortBy.direction === "desc" ? "desc" : "asc";
+                                cq = cq.orderBy(fieldName, direction);
+                            }
+                            const csnap = await cq.get();
+                            for (const d of csnap.docs) {
+                                const data = d.data();
+                                const result = { id: d.id };
+                                for (const [k, v] of Object.entries(data)) {
+                                    result[mapper.fromDb(k)] = convertTimestamp(v);
+                                }
+                                merged.set(d.id, result);
+                            }
+                        }
+                        let results = Array.from(merged.values());
+                        if (sortBy?.field) {
+                            results.sort((a, b) => {
+                                const aVal = a[sortBy.field];
+                                const bVal = b[sortBy.field];
+                                const dir = sortBy.direction === "desc" ? -1 : 1;
+                                if (aVal < bVal)
+                                    return -1 * dir;
+                                if (aVal > bVal)
+                                    return 1 * dir;
+                                return 0;
+                            });
+                        }
+                        if (offset)
+                            results = results.slice(offset);
+                        if (limit)
+                            results = results.slice(0, limit);
+                        return results;
+                    }
                     // Regular query path for non-ID queries
                     let q = applyWhereClause(col, where, mapper);
                     const notInCondition = where?.find((w) => w.operator === "notIn" ||
@@ -924,21 +1109,31 @@ export const firestoreAdapter = (config = {}) => {
                             }
                         }
                     }
-                    let q = applyWhereClause(col, where, mapper);
                     const notInCondition = where?.find((w) => w.operator === "notIn" ||
                         w.operator === "not_in");
-                    if (notInCondition) {
-                        const snap = await q.get();
-                        const fieldName = notInCondition.field;
-                        const arr = Array.isArray(notInCondition.value)
-                            ? notInCondition.value
-                            : [notInCondition.value];
-                        return snap.docs.filter((d) => {
-                            const data = d.data();
-                            const value = data[mapper.toDb(fieldName)];
-                            return !arr.includes(value);
-                        }).length;
+                    const whereClauses = getChunkedWhereClauses(where);
+                    if (notInCondition || whereClauses.length > 1) {
+                        const matchingIds = new Set();
+                        for (const whereClause of whereClauses) {
+                            const q = applyWhereClause(col, whereClause, mapper);
+                            const snap = await q.get();
+                            for (const d of snap.docs) {
+                                if (notInCondition) {
+                                    const fieldName = notInCondition.field;
+                                    const arr = Array.isArray(notInCondition.value)
+                                        ? notInCondition.value
+                                        : [notInCondition.value];
+                                    const data = d.data();
+                                    const value = data[mapper.toDb(fieldName)];
+                                    if (arr.includes(value))
+                                        continue;
+                                }
+                                matchingIds.add(d.id);
+                            }
+                        }
+                        return matchingIds.size;
                     }
+                    const q = applyWhereClause(col, where, mapper);
                     const snap = await q.count().get();
                     return snap.data().count ?? 0;
                 },

package/firestore.indexes.json

@@ -21,4 +21,3 @@
   ],
   "fieldOverrides": []
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-auth-firestore",
-  "version": "1.1.4",
+  "version": "1.2.1",
   "private": false,
   "description": "Firestore adapter for Better Auth (Firebase Admin SDK)",
   "author": "Slava Yultyyev <yultyyev@gmail.com>",
@@ -59,7 +59,7 @@
     "typescript": "^5.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.7",
+    "@biomejs/biome": "^2.4.9",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/github": "^12.0.6",
@@ -68,6 +68,20 @@
     "rimraf": "^6.1.3",
     "semantic-release": "^25.0.3",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.2"
+  },
+  "pnpm": {
+    "overrides": {
+      "@tootallnate/once@<3.0.1": ">=3.0.1",
+      "kysely@<=0.28.13": ">=0.28.14",
+      "kysely@>=0.28.12 <=0.28.13": ">=0.28.14",
+      "fast-xml-parser@>=4.0.0-beta.3 <=5.5.6": ">=5.5.7",
+      "micromatch>picomatch": "^2.3.2",
+      "picomatch@<2.3.2": ">=2.3.2",
+      "picomatch@>=4.0.0 <4.0.4": ">=4.0.4",
+      "brace-expansion@<5.0.5": ">=5.0.5",
+      "node-forge@<1.4.0": ">=1.4.0",
+      "node-forge@<=1.3.3": ">=1.4.0"
+    }
   }
 }