feat(errors): enhance index check and proper error handling

Author: Crushdada

src/errors.ts

@@ -1,6 +1,7 @@
 export enum ErrorCodes {
     NotConnectedToMongoDB = 1_000_000,
     MisconfiguredConnectionString = 1_000_001,
+    ForbiddenCollscan = 1_000_002,
 }
 
 export class MongoDBError extends Error {

src/helpers/indexCheck.ts

@@ -1,5 +1,7 @@
 import { Document } from "mongodb";
 import { NodeDriverServiceProvider } from "@mongosh/service-provider-node-driver";
+import { ErrorCodes, MongoDBError } from "../errors.js";
+
 
 /**
  * Check if the query plan uses an index
@@ -10,11 +12,22 @@ export function usesIndex(explainResult: Document): boolean {
     const stage = explainResult?.queryPlanner?.winningPlan?.stage;
     const inputStage = explainResult?.queryPlanner?.winningPlan?.inputStage;
 
-    if (stage === "IXSCAN" || stage === "COUNT_SCAN") {
+    // Check for index scan stages (including MongoDB 8.0+ stages)
+    const indexScanStages = [
+        "IXSCAN",
+        "COUNT_SCAN",
+        "EXPRESS_IXSCAN",
+        "EXPRESS_CLUSTERED_IXSCAN",
+        "EXPRESS_UPDATE",
+        "EXPRESS_DELETE",
+        "IDHACK"
+    ];
+
+    if (indexScanStages.includes(stage)) {
         return true;
     }
 
-    if (inputStage && (inputStage.stage === "IXSCAN" || inputStage.stage === "COUNT_SCAN")) {
+    if (inputStage && indexScanStages.includes(inputStage.stage)) {
         return true;
     }
 
@@ -52,7 +65,7 @@ export async function checkIndexUsage(
         const explainResult = await explainCallback();
 
         if (!usesIndex(explainResult)) {
-            throw new Error(getIndexCheckErrorMessage(database, collection, operation));
+            throw new MongoDBError(ErrorCodes.ForbiddenCollscan, getIndexCheckErrorMessage(database, collection, operation));
         }
     } catch (error) {
         if (error instanceof Error && error.message.includes("Index check failed")) {

tests/unit/indexCheck.test.ts

@@ -25,6 +25,61 @@ describe("indexCheck", () => {
             expect(usesIndex(explainResult)).toBe(true);
         });
 
+        it("should return true for IDHACK", () => {
+            const explainResult: Document = {
+                queryPlanner: {
+                    winningPlan: {
+                        stage: "IDHACK",
+                    },
+                },
+            };
+            expect(usesIndex(explainResult)).toBe(true);
+        });
+
+        it("should return true for EXPRESS_IXSCAN (MongoDB 8.0+)", () => {
+            const explainResult: Document = {
+                queryPlanner: {
+                    winningPlan: {
+                        stage: "EXPRESS_IXSCAN",
+                    },
+                },
+            };
+            expect(usesIndex(explainResult)).toBe(true);
+        });
+
+        it("should return true for EXPRESS_CLUSTERED_IXSCAN (MongoDB 8.0+)", () => {
+            const explainResult: Document = {
+                queryPlanner: {
+                    winningPlan: {
+                        stage: "EXPRESS_CLUSTERED_IXSCAN",
+                    },
+                },
+            };
+            expect(usesIndex(explainResult)).toBe(true);
+        });
+
+        it("should return true for EXPRESS_UPDATE (MongoDB 8.0+)", () => {
+            const explainResult: Document = {
+                queryPlanner: {
+                    winningPlan: {
+                        stage: "EXPRESS_UPDATE",
+                    },
+                },
+            };
+            expect(usesIndex(explainResult)).toBe(true);
+        });
+
+        it("should return true for EXPRESS_DELETE (MongoDB 8.0+)", () => {
+            const explainResult: Document = {
+                queryPlanner: {
+                    winningPlan: {
+                        stage: "EXPRESS_DELETE",
+                    },
+                },
+            };
+            expect(usesIndex(explainResult)).toBe(true);
+        });
+
         it("should return false for COLLSCAN", () => {
             const explainResult: Document = {
                 queryPlanner: {
@@ -50,6 +105,20 @@ describe("indexCheck", () => {
             expect(usesIndex(explainResult)).toBe(true);
         });
 
+        it("should return true for nested EXPRESS_IXSCAN in inputStage", () => {
+            const explainResult: Document = {
+                queryPlanner: {
+                    winningPlan: {
+                        stage: "SORT",
+                        inputStage: {
+                            stage: "EXPRESS_IXSCAN",
+                        },
+                    },
+                },
+            };
+            expect(usesIndex(explainResult)).toBe(true);
+        });
+
         it("should return false for unknown stage types", () => {
             const explainResult: Document = {
                 queryPlanner: {