refactor(ejson): perform non-lossy direct Long comparison for safe limit check

Compare the Long object directly rather than calling toNumber() first, preventing precision loss for boundary values (e.g. MAX_SAFE_INTEGER + 2) that round back to safe limits as floats. Add clarifying JSDoc documentation about the prototype recursion constraint.

Author: STiFLeR7

src/helpers/ejson.ts

@@ -4,6 +4,9 @@ import { EJSON, Long } from "bson";
  * Pre-processes an object by converting BSON Long values into EJSON format
  * if they exceed the JavaScript safe integer limits. Safe Long values are
  * converted to standard JavaScript numbers to maintain readability.
+ *
+ * Note: Recursion is restricted to plain objects (proto is Object.prototype or null)
+ * and arrays to avoid traversing and corrupting other BSON wrapper types (e.g. ObjectId, Binary).
  */
 export function serializeSafeLongs(obj: unknown): unknown {
     if (obj === null || obj === undefined) {
@@ -15,9 +18,11 @@ export function serializeSafeLongs(obj: unknown): unknown {
         (typeof obj === "object" && "_bsontype" in obj && (obj as Record<string, unknown>)._bsontype === "Long")
     ) {
         const longObj = obj as unknown as Long;
-        const num = longObj.toNumber();
-        if (num >= Number.MIN_SAFE_INTEGER && num <= Number.MAX_SAFE_INTEGER) {
-            return num;
+        const isSafe =
+            longObj.lessThanOrEqual(Long.fromNumber(Number.MAX_SAFE_INTEGER)) &&
+            longObj.greaterThanOrEqual(Long.fromNumber(Number.MIN_SAFE_INTEGER));
+        if (isSafe) {
+            return longObj.toNumber();
         }
         return { $numberLong: longObj.toString() };
     }

tests/unit/helpers/ejson.test.ts

@@ -29,6 +29,17 @@ describe("serializeSafeLongs", () => {
         expect(serializeSafeLongs(unsafeLong)).toEqual({ $numberLong: "-7583362298413593073" });
     });
 
+    it("handles boundary values around safe integer limits without float lossiness", () => {
+        // MAX_SAFE_INTEGER is 9007199254740991
+        // 9007199254740993 is unsafe, but its float representation rounds to 9007199254740992,
+        // which could trick a simple float-based safety check.
+        const unsafeBoundary = Long.fromString("9007199254740993");
+        expect(serializeSafeLongs(unsafeBoundary)).toEqual({ $numberLong: "9007199254740993" });
+
+        const safeBoundary = Long.fromString("9007199254740991");
+        expect(serializeSafeLongs(safeBoundary)).toBe(9007199254740991);
+    });
+
     it("handles nested objects and arrays", () => {
         const input = {
             a: Long.fromNumber(100),