assai 2.0.0 → 2.1.1

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

@@ -1,41 +1,41 @@
-import { Collection } from 'mongodb'
-import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
-
-/**
- * @template {import('../../../types.js').MongoDocument} T
- * @param {object} param
- * @param {import('mongodb').Filter<T>} param.query
- * @param {import('mongodb').UpdateFilter<T>} param.update
- * @param {import('mongodb').UpdateOptions} [param.options]
- * @param {() => Promise<Collection<T>>} param.getCollection
- * @param {import('../../../factories/create_mongo_collection.mjs').IcreateCollectionOptions<T>} [param.collectionOptions]
- * @returns {Promise<boolean>}
- */
-export async function updateOne({ query, update, options, collectionOptions, getCollection }) {
-    query = renameToMongoId(query)
-    stringsIntoId(query)
-    stringsIntoId(update)
-    const col = await getCollection()
-
-    const { timestamps } = collectionOptions ?? {}
-    const { updatedAt } = timestamps ?? {
-        updatedAt: 'generate'
-    }
-
-    const { $set } = update
-    const hasUpdatedAt = $set != null && $set.updatedAt != null
-    if (!hasUpdatedAt && updatedAt === 'generate') {
-        if ($set != null) {
-            // @ts-ignore
-            $set.updatedAt = new Date()
-        } else {
-            // @ts-ignore
-            update.$set = {
-                updatedAt: new Date()
-            }
-        }
-    }
-
-    const r = await col.updateOne(query, update, options)
-    return r.matchedCount > 0
+import { Collection } from 'mongodb'
+import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
+
+/**
+ * @template {import('../../../types.js').MongoDocument} T
+ * @param {object} param
+ * @param {import('mongodb').Filter<T>} param.query
+ * @param {import('mongodb').UpdateFilter<T>} param.update
+ * @param {import('mongodb').UpdateOptions} [param.options]
+ * @param {() => Promise<Collection<T>>} param.getCollection
+ * @param {import('../../../factories/create_mongo_collection.mjs').IcreateCollectionOptions<T>} [param.collectionOptions]
+ * @returns {Promise<boolean>}
+ */
+export async function updateOne({ query, update, options, collectionOptions, getCollection }) {
+    query = renameToMongoId(query)
+    query = stringsIntoId(query)
+    update = stringsIntoId(update)
+    const col = await getCollection()
+
+    const { timestamps } = collectionOptions ?? {}
+    const { updatedAt } = timestamps ?? {
+        updatedAt: 'generate'
+    }
+
+    const { $set } = update
+    const hasUpdatedAt = $set != null && $set.updatedAt != null
+    if (!hasUpdatedAt && updatedAt === 'generate') {
+        if ($set != null) {
+            // @ts-ignore
+            $set.updatedAt = new Date()
+        } else {
+            // @ts-ignore
+            update.$set = {
+                updatedAt: new Date()
+            }
+        }
+    }
+
+    const r = await col.updateOne(query, update, options)
+    return r.matchedCount > 0
 }

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

@@ -1,5 +1,5 @@
-export * from './rename_find_options.mjs'
-export * from './rename_to_dev_id.mjs'
-export * from './rename_to_mongo_id.mjs'
-
+export * from './rename_find_options.mjs'
+export * from './rename_to_dev_id.mjs'
+export * from './rename_to_mongo_id.mjs'
+
 // Contains use cases related to the id/_id field in an object.

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

@@ -1,13 +1,13 @@
-import { renameToMongoId } from './index.mjs'
-
-/**
- *
- * @param {import('../../../../types.js').FindOptions<any ,any>} options
- */
-export function renameFindOptions(options = {}) {
-    return {
-        ...options,
-        projection: renameToMongoId(options.projection),
-        sort: renameToMongoId(options.sort),
-    }
+import { renameToMongoId } from './index.mjs'
+
+/**
+ *
+ * @param {import('../../../../types.js').FindOptions<any ,any>} options
+ */
+export function renameFindOptions(options = {}) {
+    return {
+        ...options,
+        projection: renameToMongoId(options.projection),
+        sort: renameToMongoId(options.sort),
+    }
 }

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

@@ -1,14 +1,15 @@
-/**
- * ```
- * "_id" -> "id"
- * ```
- */
-export function renameToDevId(obj) {
-    if (!obj) return obj
-    let { _id, ...rest } = obj
-    if (!_id) return obj
-    return {
-        id: _id,
-        ...rest
-    }
+/**
+ * ```
+ * "_id" -> "id"
+ * ```
+ */
+export function renameToDevId(obj) {
+    if (!obj) return obj
+    let { _id, ...rest } = obj
+    if (_id === undefined) return obj
+    if (_id === null) return rest
+    return {
+        id: _id,
+        ...rest
+    }
 }

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

@@ -1,14 +1,35 @@
-/**
- * ```
- * "id" -> "_id"
- * ```
- */
-export function renameToMongoId(obj) {
-    if (!obj) return obj
-    let { id, ...rest } = obj
-    if (!id) return obj
-    return {
-        _id: id,
-        ...rest
-    }
+/**
+ * ```
+ * "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 == 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
+    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/index.mjs

@@ -1,2 +1,2 @@
-export * from './id/index.mjs'
-export * from './object_id/index.mjs'
+export * from './id/index.mjs'
+export * from './object_id/index.mjs'

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

@@ -1,33 +1,33 @@
-import { renameToMongoId } from './id/rename_to_mongo_id.mjs'
-import { stringsIntoId } from './object_id/strings_into_id.mjs'
-
-/**
- * @template {import('../../../types.js').MongoDocument} T
- * @param {object} params
- * @param {import('../../../types.js').Optional<T, 'id'>} params.document
- * @param {import('../../../factories/create_mongo_collection.mjs').IcreateCollectionOptions<T>} [params.collectionOptions]
- */
-export function inputTransformer({
-    document, collectionOptions,
-}) {
-    document = renameToMongoId(document)
-    stringsIntoId(document)
-
-    const { timestamps } = collectionOptions ?? {}
-    const { createdAt, updatedAt } = timestamps ?? {
-        createdAt: 'generate',
-        updatedAt: 'generate',
-    }
-
-    if (document.createdAt == null && createdAt === 'generate') {
-        // @ts-ignore
-        document.createdAt = new Date()
-    }
-
-    if (document.updatedAt == null && updatedAt === 'generate') {
-        // @ts-ignore
-        document.updatedAt = new Date()
-    }
-
-    return document
+import { renameToMongoId } from './id/rename_to_mongo_id.mjs'
+import { stringsIntoId } from './object_id/strings_into_id.mjs'
+
+/**
+ * @template {import('../../../types.js').MongoDocument} T
+ * @param {object} params
+ * @param {import('../../../types.js').Optional<T, 'id'>} params.document
+ * @param {import('../../../factories/create_mongo_collection.mjs').IcreateCollectionOptions<T>} [params.collectionOptions]
+ */
+export function inputTransformer({
+    document, collectionOptions,
+}) {
+    document = renameToMongoId(document)
+    document = stringsIntoId(document)
+
+    const { timestamps } = collectionOptions ?? {}
+    const { createdAt, updatedAt } = timestamps ?? {
+        createdAt: 'generate',
+        updatedAt: 'generate',
+    }
+
+    if (document.createdAt == null && createdAt === 'generate') {
+        // @ts-ignore
+        document.createdAt = new Date()
+    }
+
+    if (document.updatedAt == null && updatedAt === 'generate') {
+        // @ts-ignore
+        document.updatedAt = new Date()
+    }
+
+    return document
 }

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

@@ -1,30 +1,47 @@
-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.
- * @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 (Array.isArray(obj)) {
-        for (let i = 0; i < obj.length; i++) {
-            const item = obj[i]
-            obj[i] = idsIntoString(item)
-        }
-        return obj
-    }
-    for (const [key, value] of Object.entries(obj)) {
-        if (value instanceof ObjectId) {
-            obj[key] = value.toHexString()
-            continue
-        }
-        if (value != null && typeof value == 'object') {
-            obj[key] = idsIntoString(value)
-        }
-    }
-    return obj
-}
+/**
+ * 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 (isObjectId(obj)) return obj.toHexString()
+    if (Array.isArray(obj)) {
+        for (let i = 0; i < obj.length; i++) {
+            const item = obj[i]
+            obj[i] = idsIntoString(item)
+        }
+        return obj
+    }
+    for (const [key, value] of Object.entries(obj)) {
+        if (isObjectId(value)) {
+            obj[key] = value.toHexString()
+            continue
+        }
+        if (value != null && typeof value == 'object') {
+            obj[key] = idsIntoString(value)
+        }
+    }
+    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/index.mjs

@@ -1,4 +1,4 @@
-export * from './ids_into_strings.mjs'
-export * from './strings_into_id.mjs'
-
+export * from './ids_into_strings.mjs'
+export * from './strings_into_id.mjs'
+
 // Contains usecases related to the value ObjectId.

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

@@ -1,45 +1,91 @@
-import { ObjectId } from 'mongodb'
-
-/**
- * Converts the input value into an `ObjectId`, doing a recursive internal search if possible.
- *
- * This function will do a recursive operation if the parameter is any of the following:
- * - An object;
- * - An array;
- *
- * If the parameter is a string, then it is converted to `ObjectId` if possible.
- * @param {*} obj
- */
-export function stringsIntoId(obj) {
-    if (obj == null) return obj
-    if (isObjectIdString(obj)) return new ObjectId(obj)
-    if (typeof obj != 'object') return obj
-    if (Array.isArray(obj)) {
-        // We clone the array to prevent the original array reference to change.
-        obj = [...obj]
-
-        for (let i = 0; i < obj.length; i++) {
-            const item = obj[i]
-            obj[i] = stringsIntoId(item)
-        }
-        return obj
-    }
-    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)
-        }
-    }
-    return obj
-}
-
-/**
- *
- * @param {*} value
- * @returns {value is string}
- */
-function isObjectIdString(value) {
-    return typeof value == 'string' && ObjectId.isValid(value)
+import { ObjectId } from 'mongodb'
+
+/**
+ * Converts the input value into an `ObjectId`, doing a recursive internal search if possible.
+ *
+ * This function will do a recursive operation if the parameter is any of the following:
+ * - An object;
+ * - 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)) {
+        let hasChanges = false
+        const transformed = new Array(obj.length)
+
+        for (let i = 0; i < obj.length; i++) {
+            const item = obj[i]
+            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 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)) {
+            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 hasChanges ? transformed : obj
+}
+
+/**
+ *
+ * @param {*} value
+ * @returns {value is string}
+ */
+function isObjectIdString(value) {
+    return typeof value == 'string' && ObjectId.isValid(value)
 }

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

@@ -1,19 +1,19 @@
-import { renameToDevId } from './id/rename_to_dev_id.mjs'
-import { idsIntoString } from './object_id/ids_into_strings.mjs'
-import { timestampTransformer } from './timestamps.mjs'
-
-/**
- * @template {import('../../../types.js').MongoDocument} T
- * @param {object} p
- * @param {import('mongodb').WithId<T> | T} p.document
- * @param {import('../../../factories/create_mongo_collection.mjs').IcreateCollectionOptions<T>} [p.collectionOptions]
- */
-export function outputTransformer({
-    document, collectionOptions,
-}) {
-    if (collectionOptions) timestampTransformer(document, collectionOptions)
-    idsIntoString(document)
-    const transformedDoc = renameToDevId(document)
-
-    return transformedDoc
+import { renameToDevId } from './id/rename_to_dev_id.mjs'
+import { idsIntoString } from './object_id/ids_into_strings.mjs'
+import { timestampTransformer } from './timestamps.mjs'
+
+/**
+ * @template {import('../../../types.js').MongoDocument} T
+ * @param {object} p
+ * @param {import('mongodb').WithId<T> | T} p.document
+ * @param {import('../../../factories/create_mongo_collection.mjs').IcreateCollectionOptions<T>} [p.collectionOptions]
+ */
+export function outputTransformer({
+    document, collectionOptions,
+}) {
+    if (collectionOptions) timestampTransformer(document, collectionOptions)
+    idsIntoString(document)
+    const transformedDoc = renameToDevId(document)
+
+    return transformedDoc
 }

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

@@ -1,23 +1,33 @@
-/**
- * @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
- */
-export function timestampTransformer(doc, options) {
-    const { timestamps } = options
-    const { createdAt, updatedAt } = timestamps ?? {
-        createdAt: 'generate',
-        updatedAt: 'generate',
-    }
-
-    if (doc.createdAt == null) {
-        if (createdAt == 'fromId') {
-            doc.createdAt = doc._id.getTimestamp()
-        } else if (createdAt == 'generate') {
-            doc.createdAt = new Date()
-        }
-    }
-    if (doc.updatedAt == null && updatedAt == 'generate') {
-        doc.updatedAt = new Date()
-    }
+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
+ */
+export function timestampTransformer(doc, options) {
+    const { timestamps } = options
+    const { createdAt, updatedAt } = timestamps ?? {
+        createdAt: 'generate',
+        updatedAt: 'generate',
+    }
+
+    if (doc.createdAt == null) {
+        if (createdAt == 'fromId') {
+            const _id = doc._id
+            if (_id instanceof ObjectId) {
+                doc.createdAt = _id.getTimestamp()
+            }
+        } else if (createdAt == 'generate') {
+            doc.createdAt = new Date()
+        }
+    }
+    if (doc.updatedAt == null && updatedAt == 'generate') {
+        doc.updatedAt = new Date()
+    }
 }