assai 0.0.1

package/README.md

@@ -0,0 +1,136 @@
+This is a small package to improve some things that you, as a developer, have to deal with when working with mongo, like:
+
+- [_id](##_id)
+- [ObjectId](##ObjectId)
+- [projection](##projection)
+- [Connection String](##connection-string)
+- [Client Instance](##client-instance)
+
+# Example
+
+```js
+import {getCollection} from "assai"
+
+const collection = await getCollection()
+const docs = await collection.find({}, {limit: 10})
+/**
+ * [{id: "507f1f77bcf86cd799439011", name: "Mario"}, ...]
+ */
+```
+
+## _id
+
+Ever wanted to use just "id" in your collections instead of "_id"?
+
+This package does just that!
+
+Every data that enters the database can, optionally, have an "id". In this case, before sending the data to the native mongodb driver, the object will rename this property to "_id", which mongodb understands. This operation will be applied to `insertOne` and `insertMany` methods.
+
+Also, the methods `updateOne`, `updateMany`, `deleteOne`, `deleteMany`, `findOne` and `find` will also rename the field "id" to "_id".
+
+## ObjectId
+
+Another thing that is related to "_id" fields are the `ObjectId`s.
+
+The issue is that your application can before unnecessarily verbose. To fix that, the package will automatically convert all objectId strings into a ObjectId under the hood and all objectIds that will come from your collection, will be converted to strings.
+
+```js
+await collection.insertOne({
+    name: "Matteo",
+    groupId: "507f1f77bcf86cd799439011" // This will be stored as an ObjectId
+})
+```
+
+Every time you need a new id, you can call the `id` method:
+
+```js
+const myStringId = driver.generateNewId()
+```
+
+One example this could be useful is if have an API endpoint that accepts structured data. And you use these values to query the database. Like so:
+
+```js
+// Client code
+const response = await axios.post('/posts', {
+    userId: "507f1f77bcf86cd799439011"
+})
+```
+
+This is fine, but you will have to convert a `string` into a `ObjectId` for each field value that is an objectId in your collection. Even though this is easy to do, you could forget somewhere.
+
+Instead of carrying this risk, you can use the object as-is and the conversion will be made automatically.
+
+## projection
+
+The projection from the native mongodb driver is fine as it is. But there is one thing that is annoying: it can cause your program to fail.
+
+To be honest, this behavior makes some sense because this usually comes from a mistake the developer made. But this is not always the case and it goes against how mongodb and javascript in general behave: they avoid throwing an exception when possible.
+
+For that reason, you won't see this error while using this package:
+```
+Cannot do exclusion on field '...' in inclusion projection
+```
+
+Making projections like that valid:
+```json
+{
+    "name": true,
+    "createdAt": false
+}
+```
+
+## Connection String
+
+A default environment variable is assumed: DATABASE_URL.
+
+Which makes it easier to start a connection:
+```js
+const database = await getCollection('myCollection')
+```
+This will read the value from `process.env.DATABASE_URL`.
+
+You can still pass a custom connection string:
+```js
+const database = await getCollection('myCollection', {
+    cs: 'my connection string',
+})
+```
+
+## Client Instance
+
+If you ever worked with serverless, you will notice that you shouldn't open and close a connection everytime your function runs. You need to cache it. The package does this caching for you by default.
+
+You could also do this for simplicity, so instead of:
+```js
+// db.js
+let cachedClient = null
+export async function getDb () {
+    if (cachedClient == null) {
+        const client = await MongoClient('...')
+        cachedClient = client
+    }
+    return cachedClient.db()
+}
+
+// router.js
+import {getDb} from 'db.js'
+
+router.post('/', (req, res) => {
+    const db = await getDb()
+    const col db.collection('myCollection')
+    // ...
+})
+```
+
+You can simply write:
+```js
+router.post('/', (req, res) => {
+    const col = getCollection('myCollection')
+    // Here the connection is opened only if it is not opened already.
+    // Further calls to this route won't open a connection.
+    await driver.insertOne({
+        name: req.body.name,
+    })
+    // ...
+})
+```

package/bash/publish.sh

@@ -0,0 +1,3 @@
+npm run test || exit -1
+
+npm publish

package/index.mjs

@@ -0,0 +1 @@
+export * from './src/collection.mjs'

package/jsconfig.json

@@ -0,0 +1,10 @@
+{
+    "compilerOptions": {
+        "allowJs": true,
+        "checkJs": true,
+        "strictNullChecks": true,
+        "module": "ES2022",
+        "target": "ES2022",
+        "moduleResolution": "node"
+    }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "assai",
+  "version": "0.0.1",
+  "repository": {
+    "url": "https://github.com/TimeLord2010/assai",
+    "type": "git"
+  },
+  "description": "A simple mongodb wrapper to make mongo even easier to work with.",
+  "main": "index.mjs",
+  "scripts": {
+    "start": "node --env-file=.env index.mjs",
+    "test": "node --env-file=.env --test"
+  },
+  "keywords": [
+    "mongodb",
+    "orm"
+  ],
+  "author": "Vinícius Gabriel",
+  "license": "ISC",
+  "dependencies": {
+    "mongodb": "^6.5.0"
+  },
+  "devDependencies": {
+    "@faker-js/faker": "^8.4.1",
+    "@types/node": "^20.12.7",
+    "typescript": "^5.4.5"
+  }
+}

package/src/collection.mjs

@@ -0,0 +1,112 @@
+import { Collection } from 'mongodb'
+import { getMongoClient } from './mongo_client.mjs'
+import { deleteOneOrThrow } from './usecases/operation/additional/index.mjs'
+import {
+    count, deleteMany, deleteOne, find, findOne, insertOne, updateMany, updateOne,
+} from './usecases/operation/index.mjs'
+
+/**
+ * Generates a collection object that automatically manage ObjectId conversion to string.
+ *
+ * This method will read the string DATABASE_URL to create a connection. If you have it in another
+ * location, you will need to pass it at `connectionString` property inside the options parameter.
+ *
+ * The connection is cached by default. Use `collectionGetter` and `cachedCollectionGetter` to
+ * customize this behavior.
+ * @template {import('./types.js').MongoDocument} T
+ * @param {string} name
+ * @param {object} [options]
+ * @param {IcollectionGetter<T>} [options.collectionGetter]
+ * @param {IcollectionGetter<T>} [options.cachableCollectionGetter]
+ * @param {string} [options.connectionString]
+ */
+export async function getCollection(name, options = {}) {
+
+    /** @type {Collection<T> | null} */
+    let _collection = null
+
+    async function getCollection() {
+        const { connectionString, cachableCollectionGetter, collectionGetter } = options
+
+        // Connection getter from options
+        if (collectionGetter != null) return await collectionGetter()
+
+        // Checking cache
+        if (_collection) return _collection
+
+        // Cache function from options
+        if (cachableCollectionGetter != null) {
+            _collection = await cachableCollectionGetter()
+            return _collection
+        }
+
+        // Default connection getter
+        const client = await getMongoClient({ connectionString })
+        let db = client.db()
+        /** @type {Collection<T>} */
+        _collection = db.collection(name)
+        return _collection
+    }
+
+    return {
+        /**
+         * @param {import('mongodb').Filter<T>} query
+         */
+        count: async (query = {}) => await count({ query, getCollection }),
+        /**
+         * @template {import('./types.js').Projection<T>} K
+         * @param {import('mongodb').Filter<T>} query
+         * @param {import('./types.js').FindOptions<T, K>} options
+         */
+        find: async (query, options = {}) => await find({ query, options, getCollection }),
+        /**
+         * @template {import('./types.js').Projection<T> | undefined} K
+         * @param {import('mongodb').Filter<T>} query
+         * @param {import('./types.js').FindOptions<T,K>} options
+         */
+        findOne: async (query, options = {}) => {
+            return await findOne({ query, options, getCollection })
+        },
+        /**
+         * @param {import('./types.js').Optional<T, 'id'>} doc
+         */
+        insertOne: async (doc) => await insertOne({ doc, getCollection }),
+        /**
+         * @param {import('mongodb').Filter<T>} query
+         */
+        deleteOne: async (query) => await deleteOne({ query, getCollection }),
+        /**
+         * Deletes the first document to match the query.
+         * This method will throw an error if no documents were deleted.
+         * @param {import('mongodb').Filter<T>} query
+         * @throw {@link OperationFail} If not document was deleted
+         */
+        deleteOneOrThrow: async query => await deleteOneOrThrow({ query, getCollection }),
+        /**
+         *
+         * @param {import('mongodb').Filter<T>} query
+         */
+        deleteMany: async (query) => await deleteMany({ query, getCollection }),
+        /**
+         * @param {import('mongodb').Filter<T>} query
+         * @param {import('mongodb').UpdateFilter<T>} update
+         */
+        updateOne: async (query, update) => await updateOne({ query, update, getCollection }),
+        /**
+         * @param {import('mongodb').Filter<T>} query
+         * @param {import('mongodb').UpdateFilter<T>} update
+         */
+        updateMany: async (query, update) => await updateMany({ query, update, getCollection })
+    }
+}
+
+/**
+ * @template {import('./types.js').MongoDocument} T
+ * @callback IcollectionGetter
+ * @returns {Promise<Collection<T>>}
+ */
+
+/**
+ * @template {import('./types.js').MongoDocument} T
+ * @typedef {Awaited<ReturnType<typeof getCollection<T>>>} ICollection
+ */

package/src/data/errors/operation_fail.mjs

@@ -0,0 +1,10 @@
+export class OperationFail extends Error {
+
+    /**
+     *
+     * @param {string} msg
+     */
+    constructor(msg) {
+        super(msg)
+    }
+}

package/src/mongo_client.mjs

@@ -0,0 +1,33 @@
+import { MongoClient } from 'mongodb'
+import { OperationFail } from './data/errors/operation_fail.mjs'
+
+/** @type {MongoClient | null} */
+let client = null
+
+/**
+ *
+ * @param {object} params
+ * @param {string} [params.connectionString]
+ */
+export async function getMongoClient({
+    connectionString,
+} = {}) {
+    if (!client) {
+        function getCS() {
+            if (typeof connectionString == 'string') return connectionString
+            const DATABASE_URL = process.env.DATABASE_URL
+            if (DATABASE_URL == null) {
+                throw new OperationFail('DATABASE_URL not configured')
+            }
+            return DATABASE_URL
+        }
+        const cs = getCS()
+        client = await MongoClient.connect(cs)
+    }
+    return client
+}
+
+export async function closeMongoClient() {
+    await client?.close()
+    client = null
+}

package/src/types.ts

@@ -0,0 +1,42 @@
+import { FindOptions as FO } from 'mongodb'
+
+export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
+
+export type MongoDocument = {
+    id: string
+    [key: string]: any
+}
+
+type NonNullProjection<T extends MongoDocument> = Partial<Record<keyof T, 1 | 0>>
+
+export type Projection<T extends MongoDocument> = NonNullProjection<T> | undefined
+
+type GivenProjectionReturnType<T extends MongoDocument, P extends NonNullProjection<T>> =
+    P extends Partial<Record<keyof T, 0>>
+    ? {
+        [K in keyof T as P[K] extends 0 ? never : K]: T[K]
+    }
+    : {
+        [K in keyof T as P[K] extends 1 ? K : never]: T[K]
+    };
+
+export type ProjectionReturnType<T extends MongoDocument, P extends Projection<T>> =
+    P extends NonNullProjection<T> ? GivenProjectionReturnType<T, P> : T
+
+// export type ProjectionReturnType<T extends MongoDocument, P extends Projection<T>> =
+//     P extends Partial<Record<keyof T, 0>>
+//     ? {
+//         [K in keyof T as P[K] extends 0 ? never : K]: T[K]
+//     }
+//     : (P extends Partial<Record<keyof T, 0 | 1>> ? {
+//         [K in keyof T as P[K] extends 1 ? K : (
+//             K extends 'id' ? (
+//                 P[K] extends 0 ? never : K
+//             ) :
+//             never
+//         )]: T[K]
+//     } : T)
+
+export type FindOptions<T extends MongoDocument, K extends Projection<T>> = Omit<FO<T>, 'projection'> & {
+    projection?: K
+}

package/src/usecases/generate_new_id.mjs

@@ -0,0 +1,5 @@
+import { ObjectId } from 'mongodb'
+
+export function generateNewId() {
+    return new ObjectId().toHexString()
+}

package/src/usecases/operation/additional/delete_one_or_throw.mjs

@@ -0,0 +1,18 @@
+import { Collection } from 'mongodb'
+import { OperationFail } from '../../../data/errors/operation_fail.mjs'
+import { deleteOne } from '../delete_one.mjs'
+
+/**
+ * @template {import('../../../types.js').MongoDocument} T
+ * @param {object} param
+ * @param {import('mongodb').Filter<T>} param.query
+ * @param {() => Promise<Collection<T>>} param.getCollection
+ */
+export async function deleteOneOrThrow({
+    query, getCollection,
+}) {
+    const deleted = await deleteOne({ query, getCollection })
+    if (!deleted) {
+        throw new OperationFail('Delete one did not delete any documents')
+    }
+}

package/src/usecases/operation/additional/index.mjs

@@ -0,0 +1 @@
+export * from './delete_one_or_throw.mjs'

package/src/usecases/operation/count.mjs

@@ -0,0 +1,17 @@
+import { Collection } from 'mongodb'
+import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
+
+/**
+ * @template {import('../../types.js').MongoDocument} T
+ * @param {object} params
+ * @param {() => Promise<Collection<T>>} params.getCollection
+ * @param {import('mongodb').Filter<T>} [params.query]
+ */
+export async function count({ getCollection, query }) {
+    renameToMongoId(query)
+    stringsIntoId(query)
+
+    const col = await getCollection()
+    const count = await col.countDocuments(query)
+    return count
+}

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

@@ -0,0 +1,49 @@
+import { fakerPT_BR } from '@faker-js/faker'
+import assert from 'node:assert'
+import { after, before, describe, it } from 'node:test'
+import { mockGetCollection } from '../../../test/mock_get_collection.mjs'
+import { closeMongoClient } from '../../mongo_client.mjs'
+import { generateNewId } from '../generate_new_id.mjs'
+import { count } from './count.mjs'
+import { insertMany } from './insert_many.mjs'
+
+describe('count', () => {
+    const tag = generateNewId()
+    before(async () => {
+        /** @type {import('../../../test/mock_get_collection.mjs').ItestCollection[]} */
+        const items = []
+        for (let i = 0; i < 50; i++) {
+            items.push({
+                name: fakerPT_BR.person.fullName(),
+                tag,
+            })
+        }
+        await insertMany({
+            docs: items,
+            // @ts-ignore
+            getCollection: mockGetCollection,
+        })
+    })
+
+    after(async () => {
+        await closeMongoClient()
+    })
+
+    it('should count all inserted documents', async () => {
+        const counter = await count({
+            query: { tag },
+            // @ts-ignore
+            getCollection: mockGetCollection,
+        })
+        assert.equal(counter, 50)
+    })
+
+    it('should return 0 if the query does not match any documents', async () => {
+        const counter = await count({
+            query: { tag: generateNewId() },
+            // @ts-ignore
+            getCollection: mockGetCollection,
+        })
+        assert.equal(counter, 0)
+    })
+})

package/src/usecases/operation/delete_many.mjs

@@ -0,0 +1,16 @@
+import { Collection } from 'mongodb'
+import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
+
+/**
+ * @template {import('../../types.js').MongoDocument} T
+ * @param {object} parameter
+ * @param {import('mongodb').Filter<T>} parameter.query
+ * @param {() => Promise<Collection<T>>} parameter.getCollection
+ */
+export async function deleteMany({ query, getCollection }) {
+    renameToMongoId(query)
+    stringsIntoId(query)
+    const col = await getCollection()
+    const r = await col.deleteMany(query)
+    return r.deletedCount > 0
+}

package/src/usecases/operation/delete_one.mjs

@@ -0,0 +1,16 @@
+import { Collection } from 'mongodb'
+import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
+
+/**
+ * @template {import('../../types.js').MongoDocument} T
+ * @param {object} parameter
+ * @param {import('mongodb').Filter<T>} parameter.query
+ * @param {() => Promise<Collection<T>>} parameter.getCollection
+ */
+export async function deleteOne({ query, getCollection }) {
+    renameToMongoId(query)
+    stringsIntoId(query)
+    const col = await getCollection()
+    const r = await col.deleteOne(query)
+    return r.deletedCount > 0
+}

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

@@ -0,0 +1,30 @@
+import assert from 'node:assert'
+import { describe, it } from 'node:test'
+import { manageMockRegistry } from '../../../test/manage_mock_registry.mjs'
+import { mockGetCollection } from '../../../test/mock_get_collection.mjs'
+import { count } from './count.mjs'
+import { deleteOne } from './delete_one.mjs'
+
+describe('deleteOne', () => {
+    const { id } = manageMockRegistry({
+        name: 'Made in heaven',
+    }, {
+        deleteAtEnd: false,
+    })
+
+    it('should succeed on deleting by using registered id', async () => {
+        const deleted = await deleteOne({
+            // @ts-ignore
+            getCollection: mockGetCollection,
+            query: { id }
+        })
+        assert(deleted)
+
+        const docCount = await count({
+            // @ts-ignore
+            getCollection: mockGetCollection,
+            query: { id }
+        })
+        assert(docCount == 0)
+    })
+})

package/src/usecases/operation/find.mjs

@@ -0,0 +1,34 @@
+import { Collection } from 'mongodb'
+import {
+    idsIntoString,
+    renameFindOptions,
+    renameToDevId,
+    renameToMongoId,
+    stringsIntoId
+} from '../transformers/index.mjs'
+
+/**
+ * @template {import('../../types.js').MongoDocument} T
+ * @template {import('../../types.js').Projection<T>} K
+ * @param {object} parameter
+ * @param {() => Promise<Collection<T>>} parameter.getCollection
+ * @param {import('mongodb').Filter<T>} parameter.query
+ * @param {import('../../types.js').FindOptions<T, K>} [parameter.options]
+ * @returns {Promise<T[]>}
+ */
+export async function find({ getCollection, query, options }) {
+    renameToMongoId(query)
+    renameFindOptions(options)
+
+    stringsIntoId(query)
+
+    const col = await getCollection()
+
+    const docs = await col.find(query, options).toArray()
+    const fixedDocs = docs.map((doc) => {
+        idsIntoString(doc)
+        const transformedDoc = renameToDevId(doc)
+        return transformedDoc
+    })
+    return fixedDocs
+}

package/src/usecases/operation/find_one.mjs

@@ -0,0 +1,26 @@
+import { Collection } from 'mongodb'
+import { find } from './find.mjs'
+
+/**
+ * @template {import('../../types.js').MongoDocument} T
+ * @template {import('../../types.js').Projection<T> | undefined} K
+ * @param {object} param
+ * @param {import('mongodb').Filter<T>} param.query
+ * @param {import('../../types.js').FindOptions<T, K>} [param.options]
+ * @param {() => Promise<Collection<T>>} param.getCollection
+ */
+export async function findOne({ query, options, getCollection }) {
+    const docs = await find({
+        query,
+        options: {
+            limit: 1,
+            ...options,
+        },
+        getCollection,
+    })
+    const doc = docs[0]
+    if (doc == null) {
+        return null
+    }
+    return doc
+}

package/src/usecases/operation/find_one.test.mjs

@@ -0,0 +1,28 @@
+import assert from 'node:assert'
+import { describe, it } from 'node:test'
+import { manageMockRegistry } from '../../../test/manage_mock_registry.mjs'
+import { mockGetCollection } from '../../../test/mock_get_collection.mjs'
+import { findOne } from './find_one.mjs'
+
+describe('findOne', () => {
+
+    const { id, name } = manageMockRegistry({
+        name: 'Anna'
+    })
+
+    async function _findOne(query) {
+        const r = await findOne({
+            // @ts-ignore
+            getCollection: mockGetCollection,
+            query: query,
+        })
+        return r
+    }
+
+    it('should succeed at finding a saved document', async () => {
+        const savedDoc = await _findOne({ id })
+        assert(savedDoc)
+        assert.equal(savedDoc.id, id)
+        assert.equal(savedDoc.name, name)
+    })
+})

package/src/usecases/operation/index.mjs

@@ -0,0 +1,9 @@
+export * from './additional/index.mjs'
+export * from './count.mjs'
+export * from './delete_many.mjs'
+export * from './delete_one.mjs'
+export * from './find.mjs'
+export * from './find_one.mjs'
+export * from './insert_one.mjs'
+export * from './update_many.mjs'
+export * from './update_one.mjs'

package/src/usecases/operation/insert_many.mjs

@@ -0,0 +1,30 @@
+import { Collection, ObjectId } from 'mongodb'
+import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
+
+/**
+ * @template {import('../../types.js').MongoDocument} T
+ * @param {object} param
+ * @param {import('../../types.js').Optional<T, 'id'>[]} param.docs
+ * @param {() => Promise<Collection<T>>} param.getCollection
+ */
+export async function insertMany({ docs, getCollection }) {
+    if (docs.length == 0) return []
+    for (const doc of docs) {
+        renameToMongoId(doc)
+        stringsIntoId(doc)
+    }
+    const col = await getCollection()
+    const result = await col.insertMany(
+        // @ts-ignore
+        docs
+    )
+    let { insertedIds } = result
+    const indexes = Object.keys(insertedIds)
+    for (const index of indexes) {
+        const id = insertedIds[index]
+        if (id instanceof ObjectId) {
+            docs[index].id = id.toHexString()
+        }
+    }
+    return docs
+}

package/src/usecases/operation/insert_many.test.mjs

@@ -0,0 +1,44 @@
+import { fakerPT_BR } from '@faker-js/faker'
+import { ObjectId } from 'mongodb'
+import assert from 'node:assert'
+import { after, describe, it } from 'node:test'
+import { mockGetCollection } from '../../../test/mock_get_collection.mjs'
+import { closeMongoClient } from '../../mongo_client.mjs'
+import { generateNewId } from '../generate_new_id.mjs'
+import { insertMany } from './insert_many.mjs'
+
+describe('insertMany', () => {
+
+    after(async () => await closeMongoClient())
+
+    it('should succeed at inserting multiple data', async () => {
+        const tag = generateNewId()
+        /** @type {import('../../../test/mock_get_collection.mjs').ItestCollection[]} */
+        const items = []
+        for (let i = 0; i < 50; i++) {
+            items.push({
+                name: fakerPT_BR.person.fullName(),
+                createdAt: fakerPT_BR.date.birthdate(),
+                tag: tag,
+            })
+        }
+        const r = await insertMany({
+            docs: items,
+            // @ts-ignore
+            getCollection: mockGetCollection,
+        })
+        const ids = r.map(x => x.id)
+        const allHaveId = ids.every(x => x && ObjectId.isValid(x))
+        assert(allHaveId)
+
+        const col = await mockGetCollection()
+
+        const docs = await col.find({
+            tag: ObjectId.createFromHexString(tag),
+        }).toArray()
+        assert(docs.length == items.length)
+
+        const tagFound = docs[0].tag
+        assert(tagFound instanceof ObjectId)
+    })
+})

package/src/usecases/operation/insert_one.mjs

@@ -0,0 +1,27 @@
+import { Collection, ObjectId } from 'mongodb'
+import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
+
+/**
+ * @template {import('../../types.js').MongoDocument} T
+ * @param {object} param
+ * @param {import('../../types.js').Optional<T, 'id'>} param.doc
+ * @param {() => Promise<Collection<T>>} param.getCollection
+ */
+export async function insertOne({ doc, getCollection }) {
+    renameToMongoId(doc)
+    stringsIntoId(doc)
+    const col = await getCollection()
+    const result = await col.insertOne(
+        // @ts-ignore
+        doc
+    )
+    let id = result.insertedId
+    if (id instanceof ObjectId) {
+        // @ts-ignore
+        id = id.toHexString()
+    }
+    return {
+        id,
+        ...doc,
+    }
+}

package/src/usecases/operation/insert_one.test.mjs

@@ -0,0 +1,74 @@
+import { ObjectId } from 'mongodb'
+import assert from 'node:assert'
+import { after, describe, it } from 'node:test'
+import { mockGetCollection } from '../../../test/mock_get_collection.mjs'
+import { closeMongoClient } from '../../mongo_client.mjs'
+import { generateNewId } from '../generate_new_id.mjs'
+import { insertOne } from './insert_one.mjs'
+
+describe('insertOne', () => {
+
+    after(async () => await closeMongoClient())
+
+    async function insert(doc) {
+        await insertOne({
+            doc,
+            // @ts-ignore
+            getCollection: mockGetCollection,
+        })
+    }
+
+    it('should accept a string ids', async () => {
+        const id = generateNewId()
+        const userId = generateNewId()
+        const postId = generateNewId()
+        const addressId = generateNewId()
+        const name = 'Joseph'
+        const doc = {
+            id,
+            name,
+            userId,
+            posts: [{ postId }],
+            address: { addressId },
+        }
+        await insert(doc)
+        const col = await mockGetCollection()
+        const savedDoc = await col.findOne({ _id: new ObjectId(id) })
+        assert(savedDoc)
+
+        // Checking if normal properties are correctly set
+        assert(savedDoc.name == name)
+
+        // Checking _id is indeed an ObjectId instance
+        const _id = savedDoc._id
+        assert(_id instanceof ObjectId)
+        assert(_id.toHexString() == id)
+
+        // Checking if ids inside arrays are correctly mapped
+        const savedPostId = savedDoc.posts?.[0].postId
+        assert(savedPostId instanceof ObjectId)
+        assert(savedPostId.toHexString() == postId)
+
+        // Checking if ids inside objects are correctly mapped
+        const savedAddressId = savedDoc.address.addressId
+        assert(savedAddressId instanceof ObjectId)
+        assert(savedAddressId.toHexString() == addressId)
+    })
+
+    it('should accept ObjectId as usual', async () => {
+        const id = new ObjectId()
+        const name = 'Jotoro'
+        const doc = { id, name }
+        await insert(doc)
+
+        const col = await mockGetCollection()
+        const savedDoc = await col.findOne({ _id: id })
+        assert(savedDoc)
+
+        assert(savedDoc.name == name)
+
+        const _id = savedDoc._id
+        assert(_id instanceof ObjectId)
+        assert(_id.toHexString() == id.toHexString())
+    })
+})

package/src/usecases/operation/update_many.mjs

@@ -0,0 +1,18 @@
+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 {() => Promise<Collection<T>>} param.getCollection
+ */
+export async function updateMany({ query, update, getCollection }) {
+    renameToMongoId(query)
+    stringsIntoId(query)
+    stringsIntoId(update)
+    const col = await getCollection()
+    const r = await col.updateMany(query, update)
+    return r.matchedCount > 0
+}

package/src/usecases/operation/update_one.mjs

@@ -0,0 +1,18 @@
+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 {() => Promise<Collection<T>>} param.getCollection
+ */
+export async function updateOne({ query, update, getCollection }) {
+    renameToMongoId(query)
+    stringsIntoId(query)
+    stringsIntoId(update)
+    const col = await getCollection()
+    const r = await col.updateOne(query, update)
+    return r.matchedCount > 0
+}

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

@@ -0,0 +1,56 @@
+import { ObjectId } from 'mongodb'
+import assert from 'node:assert'
+import { after, describe, it } from 'node:test'
+import { manageMockRegistry } from '../../../test/manage_mock_registry.mjs'
+import { mockGetCollection } from '../../../test/mock_get_collection.mjs'
+import { closeMongoClient } from '../../mongo_client.mjs'
+import { generateNewId } from '../generate_new_id.mjs'
+import { updateOne } from './update_one.mjs'
+
+describe('updateOne', () => {
+
+    const { id } = manageMockRegistry({
+        name: 'Jolyne Cujoh',
+    })
+
+    after(() => {
+        closeMongoClient()
+    })
+
+    it('should update document using string id', async () => {
+        const updatedName = 'Jolyne'
+        const updated = await updateOne({
+            // @ts-ignore
+            getCollection: mockGetCollection,
+            query: {
+                id,
+            },
+            update: {
+                $set: { name: updatedName }
+            },
+        })
+        assert(updated)
+        const col = await mockGetCollection()
+        const doc = await col.findOne({
+            _id: new ObjectId(id)
+        })
+        assert(doc)
+        assert(doc?.name == updatedName)
+    })
+
+    it('should not update any document using non registered id', async () => {
+        const updated = await updateOne({
+            // @ts-ignore
+            getCollection: mockGetCollection,
+            query: {
+                id: generateNewId(),
+            },
+            update: {
+                $set: {
+                    createdAt: new Date()
+                },
+            },
+        })
+        assert(!updated)
+    })
+})

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

@@ -0,0 +1,5 @@
+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/transformers/id/rename_find_options.mjs

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

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

@@ -0,0 +1,16 @@
+/**
+ * ```
+ * "_id" -> "id"
+ * ```
+ */
+export function renameToDevId(obj) {
+    if (!obj) return obj
+    let { _id, ...rest } = obj
+    if (!_id) return obj
+    delete obj['_id']
+    // if (_id instanceof ObjectId) {
+    //     _id = _id.toHexString()
+    // }
+    obj.id = _id
+    return obj
+}

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

@@ -0,0 +1,16 @@
+/**
+ * ```
+ * "id" -> "_id"
+ * ```
+ */
+export function renameToMongoId(obj) {
+    if (!obj) return obj
+    let { id, ...rest } = obj
+    if (!id) return obj
+    delete obj['id']
+    // if (_id instanceof ObjectId) {
+    //     _id = _id.toHexString()
+    // }
+    obj._id = id
+    return obj
+}

package/src/usecases/transformers/index.mjs

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

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

@@ -0,0 +1,30 @@
+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
+}

package/src/usecases/transformers/object_id/index.mjs

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

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

@@ -0,0 +1,42 @@
+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)) {
+        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)
+}

package/test/manage_mock_registry.mjs

@@ -0,0 +1,53 @@
+import { fakerPT_BR } from '@faker-js/faker'
+import { ObjectId } from 'mongodb'
+import { after, before } from 'node:test'
+import { closeMongoClient } from '../src/mongo_client.mjs'
+import { generateNewId } from '../src/usecases/generate_new_id.mjs'
+import { deleteOne } from '../src/usecases/operation/delete_one.mjs'
+import { insertOne } from '../src/usecases/operation/insert_one.mjs'
+import { mockGetCollection } from './mock_get_collection.mjs'
+
+/**
+ *
+ * @param {import('./mock_get_collection.mjs').ItestCollection} param
+ * @param {object} options
+ * @param {boolean} [options.deleteAtEnd]
+ */
+export function manageMockRegistry({ tag, ...rest } = {}, {
+    deleteAtEnd = true
+} = {}) {
+
+    const id = generateNewId()
+    const name = rest.name ?? fakerPT_BR.person.fullName()
+
+    before(async () => {
+        await insertOne({
+            // @ts-ignore
+            getCollection: mockGetCollection,
+            doc: {
+                id,
+                createdAt: new Date(),
+                tag,
+                name: name,
+                ...rest,
+            },
+        })
+    })
+
+    after(async () => {
+        if (deleteAtEnd) {
+            await deleteOne({
+                query: {
+                    _id: ObjectId.createFromHexString(id)
+                },
+                // @ts-ignore
+                getCollection: mockGetCollection,
+            })
+        }
+        await closeMongoClient()
+    })
+
+    return {
+        id, name
+    }
+}

package/test/mock_get_collection.mjs

@@ -0,0 +1,21 @@
+import { Collection, ObjectId } from 'mongodb'
+import { getMongoClient } from '../src/mongo_client.mjs'
+
+export async function mockGetCollection(collectionName = 'test') {
+    const client = await getMongoClient()
+    const db = client.db()
+    /** @type {Collection<ItestCollection>} */
+    const collection = db.collection(collectionName)
+    return collection
+}
+
+/**
+ * @typedef {object} ItestCollection
+ * @property {ObjectId} [_id]
+ * @property {string} [id]
+ * @property {string} [name]
+ * @property {string | ObjectId} [tag]
+ * @property {Date} [createdAt]
+ * @property {object[]} [posts]
+ * @property {object} [address]
+ */