assai 2.1.0 → 2.1.2

package/dist/src/__test/mock_get_collection.d.mts

@@ -6,6 +6,8 @@ export type ItestCollection = {
     tag?: string | ObjectId | undefined;
     createdAt?: Date | undefined;
     posts?: any[] | undefined;
+    score?: number | undefined;
+    group?: string | undefined;
     address?: object;
 };
 import { Collection } from 'mongodb';

package/dist/src/usecases/mongo/transformers/id/rename_to_dev_id.d.mts

@@ -2,5 +2,8 @@
  * ```
  * "_id" -> "id"
  * ```
+ * Recursively renames all `_id` keys to `id` in objects and arrays.
+ * Does not mutate the original input.
+ * @param {*} obj
  */
 export function renameToDevId(obj: any): any;

package/dist/src/usecases/mongo/transformers/id/rename_to_mongo_id.d.mts

@@ -2,5 +2,8 @@
  * ```
  * "id" -> "_id"
  * ```
+ * Recursively renames all `id` keys to `_id` in objects and arrays.
+ * Does not mutate the original input.
+ * @param {*} obj
  */
 export function renameToMongoId(obj: any): any;

package/dist/src/usecases/mongo/transformers/object_id/ids_into_strings.d.mts

@@ -2,6 +2,11 @@
  * Convert the parameter from `ObjectId` into string whenever possible.
  *
  * If an object or array is given, this function will be applied recursively.
+ *
+ * Uses duck-typing (`_bsontype === 'ObjectId'`) instead of `instanceof` to
+ * safely identify ObjectId values across different instances of the `mongodb`
+ * / `bson` package (e.g. when the host project and this library resolve to
+ * separate copies of the package).
  * @param {*} obj
  */
 export function idsIntoString(obj: any): any;

package/dist/src/usecases/mongo/transformers/object_id/strings_into_id.d.mts

@@ -6,6 +6,9 @@
  * - An array;
  *
  * If the parameter is a string, then it is converted to `ObjectId` if possible.
+ *
+ * This function does not mutate the original input. It preserves reference equality for
+ * objects and special types (like Date) that don't need transformation.
  * @param {*} obj
  */
 export function stringsIntoId(obj: any): any;

package/dist/src/usecases/mongo/transformers/timestamps.d.mts

@@ -1,4 +1,9 @@
 /**
+ * Transforms a document by adding or updating timestamp fields (createdAt and updatedAt).
+ * If createdAt is not set, it can be generated as a new Date or extracted from the document's ObjectId.
+ * If updatedAt is not set, it is generated as a new Date.
+ * The document is modified in place.
+ *
  * @template {import('../../../types.js').MongoDocument} T
  * @param {import('mongodb').WithId<T> | import('../../../types.js').MongoDocument} doc
  * @param {import('../../../factories/create_mongo_collection.mjs').IcreateCollectionOptions<T>} options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assai",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "repository": {
     "url": "https://github.com/TimeLord2010/assai",
     "type": "git"
@@ -28,8 +28,8 @@
   ],
   "author": "Vinícius Gabriel",
   "license": "ISC",
-  "dependencies": {
-    "mongodb": "^7.0.0"
+  "peerDependencies": {
+    "mongodb": ">=4.0.0"
   },
   "devDependencies": {
     "@faker-js/faker": "^8.4.1",

package/src/__test/mock_get_collection.mjs

@@ -17,5 +17,7 @@ export async function mockGetCollection(collectionName = 'test') {
  * @property {string | ObjectId} [tag]
  * @property {Date} [createdAt]
  * @property {object[]} [posts]
+ * @property {number} [score]
+ * @property {string} [group]
  * @property {object} [address]
  */

package/src/usecases/mongo/operation/aggregate.mjs

@@ -12,15 +12,10 @@ import { outputTransformer } from '../transformers/output_transformer.mjs'
  * @returns {Promise<T[]>}
  */
 export async function aggregate({ getCollection, pipeline, options, collectionOptions }) {
-    for (const stage of pipeline) {
-        if (stage.$match != null) {
-            stage.$match = renameToMongoId(stage.$match)
-        }
-    }
-    pipeline = stringsIntoId(pipeline)
+    const finalPipeline = stringsIntoId(renameToMongoId(pipeline))
 
     const col = await getCollection()
-    const docs = await col.aggregate(pipeline, options).toArray()
+    const docs = await col.aggregate(finalPipeline, options).toArray()
     // @ts-ignore
     return docs.map((doc) => outputTransformer({ document: doc, collectionOptions }))
 }

package/src/usecases/mongo/operation/bulk_write.mjs

@@ -21,22 +21,22 @@ export async function bulkWrite({ getCollection, operations, options, collection
             })
         } else if (o.updateOne != null) {
             o.updateOne.filter = renameToMongoId(o.updateOne.filter)
-            stringsIntoId(o.updateOne.filter)
-            stringsIntoId(o.updateOne.update)
+            o.updateOne.filter = stringsIntoId(o.updateOne.filter)
+            o.updateOne.update = stringsIntoId(o.updateOne.update)
         } else if (o.updateMany != null) {
             o.updateMany.filter = renameToMongoId(o.updateMany.filter)
-            stringsIntoId(o.updateMany.filter)
-            stringsIntoId(o.updateMany.update)
+            o.updateMany.filter = stringsIntoId(o.updateMany.filter)
+            o.updateMany.update = stringsIntoId(o.updateMany.update)
         } else if (o.deleteOne != null) {
             o.deleteOne.filter = renameToMongoId(o.deleteOne.filter)
-            stringsIntoId(o.deleteOne.filter)
+            o.deleteOne.filter = stringsIntoId(o.deleteOne.filter)
         } else if (o.deleteMany != null) {
             o.deleteMany.filter = renameToMongoId(o.deleteMany.filter)
-            stringsIntoId(o.deleteMany.filter)
+            o.deleteMany.filter = stringsIntoId(o.deleteMany.filter)
         } else if (o.replaceOne != null) {
             o.replaceOne.filter = renameToMongoId(o.replaceOne.filter)
-            stringsIntoId(o.replaceOne.filter)
-            stringsIntoId(o.replaceOne.replacement)
+            o.replaceOne.filter = stringsIntoId(o.replaceOne.filter)
+            o.replaceOne.replacement = stringsIntoId(o.replaceOne.replacement)
         }
     }
 

package/src/usecases/mongo/operation/count.mjs

@@ -9,7 +9,7 @@ import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
  */
 export async function count({ getCollection, query }) {
     query = renameToMongoId(query)
-    stringsIntoId(query)
+    query = stringsIntoId(query)
 
     const col = await getCollection()
     const count = await col.countDocuments(query)

package/src/usecases/mongo/operation/delete_many.mjs

@@ -9,7 +9,7 @@ import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
  */
 export async function deleteMany({ query, getCollection }) {
     query = renameToMongoId(query)
-    stringsIntoId(query)
+    query = stringsIntoId(query)
     const col = await getCollection()
     const r = await col.deleteMany(query)
     return r.deletedCount

package/src/usecases/mongo/operation/delete_one.mjs

@@ -10,7 +10,7 @@ import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
  */
 export async function deleteOne({ query, getCollection }) {
     query = renameToMongoId(query)
-    stringsIntoId(query)
+    query = stringsIntoId(query)
     const col = await getCollection()
     const r = await col.deleteOne(query)
     return r.deletedCount > 0

package/src/usecases/mongo/operation/find.mjs

@@ -20,7 +20,7 @@ export async function find({ getCollection, query, options, collectionOptions })
     query = renameToMongoId(query)
     options = renameFindOptions(options)
 
-    stringsIntoId(query)
+    query = stringsIntoId(query)
 
     const col = await getCollection()
 

package/src/usecases/mongo/operation/find_one_and_delete.mjs

@@ -13,7 +13,7 @@ import { outputTransformer } from '../transformers/output_transformer.mjs'
  */
 export async function findOneAndDelete({ query, options, collectionOptions, getCollection }) {
     query = renameToMongoId(query)
-    stringsIntoId(query)
+    query = stringsIntoId(query)
     const col = await getCollection()
 
     const doc = await col.findOneAndDelete(query, options ?? {})

package/src/usecases/mongo/operation/find_one_and_replace.mjs

@@ -14,7 +14,7 @@ import { outputTransformer } from '../transformers/output_transformer.mjs'
  */
 export async function findOneAndReplace({ query, replacement, options, collectionOptions, getCollection }) {
     query = renameToMongoId(query)
-    stringsIntoId(query)
+    query = stringsIntoId(query)
     const col = await getCollection()
 
     const doc = await col.findOneAndReplace(query, replacement, options ?? {})

package/src/usecases/mongo/operation/find_one_and_update.mjs

@@ -14,8 +14,8 @@ import { outputTransformer } from '../transformers/output_transformer.mjs'
  */
 export async function findOneAndUpdate({ query, update, options, collectionOptions, getCollection }) {
     query = renameToMongoId(query)
-    stringsIntoId(query)
-    stringsIntoId(update)
+    query = stringsIntoId(query)
+    update = stringsIntoId(update)
     const col = await getCollection()
 
     const { timestamps } = collectionOptions ?? {}

package/src/usecases/mongo/operation/update_many.mjs

@@ -12,8 +12,8 @@ import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
  */
 export async function updateMany({ query, update, options, collectionOptions, getCollection }) {
     query = renameToMongoId(query)
-    stringsIntoId(query)
-    stringsIntoId(update)
+    query = stringsIntoId(query)
+    update = stringsIntoId(update)
 
     const { timestamps } = collectionOptions ?? {}
     const { updatedAt } = timestamps ?? {

package/src/usecases/mongo/operation/update_one.mjs

@@ -13,8 +13,8 @@ import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
  */
 export async function updateOne({ query, update, options, collectionOptions, getCollection }) {
     query = renameToMongoId(query)
-    stringsIntoId(query)
-    stringsIntoId(update)
+    query = stringsIntoId(query)
+    update = stringsIntoId(update)
     const col = await getCollection()
 
     const { timestamps } = collectionOptions ?? {}

package/src/usecases/mongo/transformers/id/rename_to_dev_id.mjs

@@ -2,13 +2,35 @@
  * ```
  * "_id" -> "id"
  * ```
+ * Recursively renames all `_id` keys to `id` in objects and arrays.
+ * Does not mutate the original input.
+ * @param {*} obj
  */
 export function renameToDevId(obj) {
-    if (!obj) return obj
-    let { _id, ...rest } = obj
-    if (!_id) return obj
-    return {
-        id: _id,
-        ...rest
+    if (obj == null) return obj
+    if (typeof obj !== 'object') return obj
+    if (obj instanceof Date) return obj
+
+    if (Array.isArray(obj)) {
+        let hasChanges = false
+        const transformed = new Array(obj.length)
+        for (let i = 0; i < obj.length; i++) {
+            const item = obj[i]
+            const transformedItem = renameToDevId(item)
+            transformed[i] = transformedItem
+            if (transformedItem !== item) hasChanges = true
+        }
+        return hasChanges ? transformed : obj
     }
+
+    let hasChanges = false
+    /** @type {Record<string, any>} */
+    const transformed = {}
+    for (const [key, value] of Object.entries(obj)) {
+        const newKey = key === '_id' ? 'id' : key
+        const newValue = renameToDevId(value)
+        transformed[newKey] = newValue
+        if (newKey !== key || newValue !== value) hasChanges = true
+    }
+    return hasChanges ? transformed : obj
 }

package/src/usecases/mongo/transformers/id/rename_to_mongo_id.mjs

@@ -2,13 +2,35 @@
  * ```
  * "id" -> "_id"
  * ```
+ * Recursively renames all `id` keys to `_id` in objects and arrays.
+ * Does not mutate the original input.
+ * @param {*} obj
  */
 export function renameToMongoId(obj) {
-    if (!obj) return obj
-    let { id, ...rest } = obj
-    if (!id) return obj
-    return {
-        _id: id,
-        ...rest
+    if (obj == null) return obj
+    if (typeof obj !== 'object') return obj
+    if (obj instanceof Date) return obj
+
+    if (Array.isArray(obj)) {
+        let hasChanges = false
+        const transformed = new Array(obj.length)
+        for (let i = 0; i < obj.length; i++) {
+            const item = obj[i]
+            const transformedItem = renameToMongoId(item)
+            transformed[i] = transformedItem
+            if (transformedItem !== item) hasChanges = true
+        }
+        return hasChanges ? transformed : obj
     }
+
+    let hasChanges = false
+    /** @type {Record<string, any>} */
+    const transformed = {}
+    for (const [key, value] of Object.entries(obj)) {
+        const newKey = key === 'id' ? '_id' : key
+        const newValue = renameToMongoId(value)
+        transformed[newKey] = newValue
+        if (newKey !== key || newValue !== value) hasChanges = true
+    }
+    return hasChanges ? transformed : obj
 }

package/src/usecases/mongo/transformers/input_transformer.mjs

@@ -11,7 +11,7 @@ export function inputTransformer({
     document, collectionOptions,
 }) {
     document = renameToMongoId(document)
-    stringsIntoId(document)
+    document = stringsIntoId(document)
 
     const { timestamps } = collectionOptions ?? {}
     const { createdAt, updatedAt } = timestamps ?? {

package/src/usecases/mongo/transformers/object_id/ids_into_strings.mjs

@@ -1,15 +1,18 @@
-import { ObjectId } from 'mongodb'
-
 /**
  * Convert the parameter from `ObjectId` into string whenever possible.
  *
  * If an object or array is given, this function will be applied recursively.
+ *
+ * Uses duck-typing (`_bsontype === 'ObjectId'`) instead of `instanceof` to
+ * safely identify ObjectId values across different instances of the `mongodb`
+ * / `bson` package (e.g. when the host project and this library resolve to
+ * separate copies of the package).
  * @param {*} obj
  */
 export function idsIntoString(obj) {
     if (obj == null) return obj
     if (typeof obj != 'object') return obj
-    if (obj instanceof ObjectId) return obj.toHexString()
+    if (isObjectId(obj)) return obj.toHexString()
     if (Array.isArray(obj)) {
         for (let i = 0; i < obj.length; i++) {
             const item = obj[i]
@@ -18,7 +21,7 @@ export function idsIntoString(obj) {
         return obj
     }
     for (const [key, value] of Object.entries(obj)) {
-        if (value instanceof ObjectId) {
+        if (isObjectId(value)) {
             obj[key] = value.toHexString()
             continue
         }
@@ -27,4 +30,18 @@ export function idsIntoString(obj) {
         }
     }
     return obj
-}
+}
+
+/**
+ * Duck-type check for BSON ObjectId values.
+ *
+ * Using `_bsontype` instead of `instanceof ObjectId` avoids false negatives
+ * that occur when the host project and this package resolve to different copies
+ * of the `mongodb` / `bson` module, which makes `instanceof` return `false`
+ * even for legitimate ObjectId instances.
+ * @param {*} value
+ * @returns {boolean}
+ */
+function isObjectId(value) {
+    return value != null && typeof value == 'object' && value._bsontype === 'ObjectId'
+}

package/src/usecases/mongo/transformers/object_id/strings_into_id.mjs

@@ -8,31 +8,77 @@ import { ObjectId } from 'mongodb'
  * - An array;
  *
  * If the parameter is a string, then it is converted to `ObjectId` if possible.
+ *
+ * This function does not mutate the original input. It preserves reference equality for
+ * objects and special types (like Date) that don't need transformation.
  * @param {*} obj
  */
 export function stringsIntoId(obj) {
     if (obj == null) return obj
     if (isObjectIdString(obj)) return new ObjectId(obj)
     if (typeof obj != 'object') return obj
+
+    // Check if this object/array needs any transformation
+    const transformed = _transformRecursive(obj)
+    return transformed
+}
+
+/**
+ * Recursively transforms ObjectId hex strings to ObjectId instances.
+ * Returns the original reference if no changes are needed, or a new object if changes are made.
+ * @param {*} obj
+ * @returns {*}
+ */
+function _transformRecursive(obj) {
+    if (obj == null || typeof obj != 'object') return obj
+
+    // Don't clone or transform special objects like Date
+    if (obj instanceof Date) return obj
+
     if (Array.isArray(obj)) {
-        // We clone the array to prevent the original array reference to change.
-        obj = [...obj]
+        let hasChanges = false
+        const transformed = new Array(obj.length)
 
         for (let i = 0; i < obj.length; i++) {
             const item = obj[i]
-            obj[i] = stringsIntoId(item)
+            if (isObjectIdString(item)) {
+                transformed[i] = new ObjectId(item)
+                hasChanges = true
+            } else if (item != null && typeof item == 'object') {
+                const transformedItem = _transformRecursive(item)
+                transformed[i] = transformedItem
+                if (transformedItem !== item) {
+                    hasChanges = true
+                }
+            } else {
+                transformed[i] = item
+            }
         }
-        return obj
+
+        return hasChanges ? transformed : obj
     }
+
+    // Handle plain objects
+    let hasChanges = false
+    /** @type {Record<string, any>} */
+    const transformed = {}
+
     for (const [key, value] of Object.entries(obj)) {
         if (isObjectIdString(value)) {
-            obj[key] = ObjectId.createFromHexString(value)
-        }
-        if (value != null && typeof value == 'object') {
-            obj[key] = stringsIntoId(value)
+            transformed[key] = ObjectId.createFromHexString(value)
+            hasChanges = true
+        } else if (value != null && typeof value == 'object') {
+            const transformedValue = _transformRecursive(value)
+            transformed[key] = transformedValue
+            if (transformedValue !== value) {
+                hasChanges = true
+            }
+        } else {
+            transformed[key] = value
         }
     }
-    return obj
+
+    return hasChanges ? transformed : obj
 }
 
 /**

package/src/usecases/mongo/transformers/timestamps.mjs

@@ -1,6 +1,11 @@
 import { ObjectId } from 'mongodb'
 
 /**
+ * Transforms a document by adding or updating timestamp fields (createdAt and updatedAt).
+ * If createdAt is not set, it can be generated as a new Date or extracted from the document's ObjectId.
+ * If updatedAt is not set, it is generated as a new Date.
+ * The document is modified in place.
+ *
  * @template {import('../../../types.js').MongoDocument} T
  * @param {import('mongodb').WithId<T> | import('../../../types.js').MongoDocument} doc
  * @param {import('../../../factories/create_mongo_collection.mjs').IcreateCollectionOptions<T>} options