assai 0.1.4 → 0.2.0

package/README.md

@@ -9,9 +9,9 @@ This is a small package to improve some things that you, as a developer, have to
 # Example
 
 ```js
-import {getCollection} from "assai"
+import {createMongoCollection} from "assai"
 
-const collection = await getCollection()
+const collection = await createMongoCollection()
 const docs = await collection.find({}, {limit: 10})
 /**
  * [{id: "507f1f77bcf86cd799439011", name: "Mario"}, ...]
@@ -85,13 +85,13 @@ A default environment variable is assumed: DATABASE_URL.
 
 Which makes it easier to start a connection:
 ```js
-const database = await getCollection('myCollection')
+const database = await createMongoCollection('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', {
+const database = await createMongoCollection('myCollection', {
     cs: 'my connection string',
 })
 ```
@@ -125,7 +125,7 @@ router.post('/', (req, res) => {
 You can simply write:
 ```js
 router.post('/', (req, res) => {
-    const col = getCollection('myCollection')
+    const col = createMongoCollection('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({

package/index.mjs

@@ -1,2 +1,2 @@
-export * from './src/collection.mjs'
-export * from './src/mongo_client.mjs'
+export * from './src/factories/index.mjs'
+export * from './src/usecases/index.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assai",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "repository": {
     "url": "https://github.com/TimeLord2010/assai",
     "type": "git"

package/src/{collection.mjs → factories/create_mongo_collection.mjs}

@@ -1,9 +1,11 @@
 import { Collection } from 'mongodb'
-import { getMongoClient } from './mongo_client.mjs'
-import { deleteOneOrThrow } from './usecases/operation/additional/index.mjs'
 import {
-    count, deleteMany, deleteOne, find, findOne, insertMany, insertOne, updateMany, updateOne,
-} from './usecases/operation/index.mjs'
+    count, deleteMany, deleteOne,
+    deleteOneOrThrow,
+    find, findOne,
+    getClient,
+    insertMany, insertOne, updateMany, updateOne
+} from '../usecases/mongo/index.mjs'
 
 /**
  * Generates a collection object that automatically manage ObjectId conversion to string.
@@ -13,14 +15,11 @@ import {
  *
  * The connection is cached by default. Use `collectionGetter` and `cachedCollectionGetter` to
  * customize this behavior.
- * @template {import('./types.js').MongoDocument} T
+ * @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]
+ * @param {IcreateCollectionOptions<T>} [options]
  */
-export async function getCollection(name, options = {}) {
+export async function createMongoCollection(name, options = {}) {
 
     /** @type {Collection<T> | null} */
     let _collection = null
@@ -41,7 +40,7 @@ export async function getCollection(name, options = {}) {
         }
 
         // Default connection getter
-        const client = await getMongoClient({ connectionString })
+        const client = await getClient({ connectionString })
         let db = client.db()
         /** @type {Collection<T>} */
         _collection = db.collection(name)
@@ -54,33 +53,35 @@ export async function getCollection(name, options = {}) {
          */
         count: async (query = {}) => await count({ query, getCollection }),
         /**
-         * @template {import('./types.js').Projection<T>} K
+         * @template {import('../types.js').Projection<T>} K
          * @param {import('mongodb').Filter<T>} query
-         * @param {import('./types.js').FindOptions<T, K>} options
+         * @param {import('../types.js').FindOptions<T, K>} options
          * @returns {Promise<T[]>}
          */
         find: async (query, options = {}) => await find({ query, options, getCollection }),
         /**
-         * @template {import('./types.js').Projection<T> | undefined} K
+         * @template {import('../types.js').Projection<T> | undefined} K
          * @param {import('mongodb').Filter<T>} query
-         * @param {import('./types.js').FindOptions<T,K>} options
+         * @param {import('../types.js').FindOptions<T,K>} options
          * @returns {Promise<T | null>}
          */
         findOne: async (query, options = {}) => {
             return await findOne({ query, options, getCollection })
         },
         /**
-         * @param {import('./types.js').Optional<T, 'id'>} doc
-         * @returns {ReturnType<typeof insertOne<T>>}
+         * @param {import('../types.js').Optional<T, 'id'>} doc
+         * @returns {Promise<T>}
          */
         insertOne: async (doc) => await insertOne({ doc, getCollection }),
         /**
          *
-         * @param {import('./types.js').Optional<T, 'id'>[]} docs
+         * @param {import('../types.js').Optional<T, 'id'>[]} docs
+         * @returns {Promise<T[]>}
          */
         insertMany: async (docs) => await insertMany({ docs, getCollection }),
         /**
          * @param {import('mongodb').Filter<T>} query
+         * @returns {Promise<boolean>}
          */
         deleteOne: async (query) => await deleteOne({ query, getCollection }),
         /**
@@ -109,12 +110,29 @@ export async function getCollection(name, options = {}) {
 }
 
 /**
- * @template {import('./types.js').MongoDocument} T
+ * @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
+ * @template {import('../types.js').MongoDocument} T
+ * @typedef {object} IcreateCollectionOptions
+ * @property {IcollectionGetter<T>} [options.collectionGetter]
+ * A custom function to get the collection object from mongodb driver.
+ *
+ * This will be not be cached and will be used on every operation such as insertOne or findOne.
+ *
+ * If you wish to cache the collection object, see `cachableCollectionGetter`.
+ *
+ * @property {IcollectionGetter<T>} [options.cachableCollectionGetter]
+ * Same as `collectionGetter`. But the object is cached.
+ *
+ * @property {string} [options.connectionString]
+ * A custom connection string. If none is given, `process.env.DATABASE_URL` will be used.
+ */
+
+/**
+ * @template {import('../types.js').MongoDocument} T
+ * @typedef {Awaited<ReturnType<typeof createMongoCollection<T>>>} ICollection
  */

package/src/factories/index.mjs

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

package/src/types.ts

@@ -7,6 +7,10 @@ export type MongoDocument = {
     [key: string]: any
 }
 
+export type RequiredIfPresent<T, U> = {
+    [P in keyof T]: P extends keyof U ? Required<T[P]> : T[P];
+};
+
 type NonNullProjection<T extends MongoDocument> = Partial<Record<keyof T, 1 | 0>>
 
 export type Projection<T extends MongoDocument> = NonNullProjection<T> | undefined

package/src/usecases/index.mjs

@@ -0,0 +1 @@
+export * as mongo from './mongo/index.mjs'

package/src/usecases/mongo/index.mjs

@@ -0,0 +1,3 @@
+export * from './generate_new_id.mjs'
+export * from './mongo_client.mjs'
+export * from './operation/index.mjs'

package/src/{mongo_client.mjs → usecases/mongo/mongo_client.mjs}

@@ -1,5 +1,5 @@
 import { MongoClient } from 'mongodb'
-import { OperationFail } from './data/errors/operation_fail.mjs'
+import { OperationFail } from '../../data/errors/operation_fail.mjs'
 
 /** @type {MongoClient | null} */
 let client = null
@@ -9,7 +9,7 @@ let client = null
  * @param {object} params
  * @param {string} [params.connectionString]
  */
-export async function getMongoClient({
+export async function getClient({
     connectionString,
 } = {}) {
     if (!client) {
@@ -27,7 +27,7 @@ export async function getMongoClient({
     return client
 }
 
-export async function closeMongoClient() {
+export async function closeClient() {
     await client?.close()
     client = null
 }

package/src/usecases/{operation → mongo/operation}/additional/delete_one_or_throw.mjs

@@ -1,9 +1,9 @@
 import { Collection } from 'mongodb'
-import { OperationFail } from '../../../data/errors/operation_fail.mjs'
+import { OperationFail } from '../../../../data/errors/operation_fail.mjs'
 import { deleteOne } from '../delete_one.mjs'
 
 /**
- * @template {import('../../../types.js').MongoDocument} T
+ * @template {import('../../../../types.js').MongoDocument} T
  * @param {object} param
  * @param {import('mongodb').Filter<T>} param.query
  * @param {() => Promise<Collection<T>>} param.getCollection

package/src/usecases/{operation → mongo/operation}/count.mjs

@@ -2,7 +2,7 @@ import { Collection } from 'mongodb'
 import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
 
 /**
- * @template {import('../../types.js').MongoDocument} T
+ * @template {import('../../../types.js').MongoDocument} T
  * @param {object} params
  * @param {() => Promise<Collection<T>>} params.getCollection
  * @param {import('mongodb').Filter<T>} [params.query]

package/src/usecases/{operation → mongo/operation}/delete_many.mjs

@@ -2,7 +2,7 @@ import { Collection } from 'mongodb'
 import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
 
 /**
- * @template {import('../../types.js').MongoDocument} T
+ * @template {import('../../../types.js').MongoDocument} T
  * @param {object} parameter
  * @param {import('mongodb').Filter<T>} parameter.query
  * @param {() => Promise<Collection<T>>} parameter.getCollection

package/src/usecases/{operation → mongo/operation}/delete_one.mjs

@@ -2,10 +2,11 @@ import { Collection } from 'mongodb'
 import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
 
 /**
- * @template {import('../../types.js').MongoDocument} T
+ * @template {import('../../../types.js').MongoDocument} T
  * @param {object} parameter
  * @param {import('mongodb').Filter<T>} parameter.query
  * @param {() => Promise<Collection<T>>} parameter.getCollection
+ * @returns {Promise<boolean>}
  */
 export async function deleteOne({ query, getCollection }) {
     renameToMongoId(query)

package/src/usecases/{operation → mongo/operation}/find.mjs

@@ -8,12 +8,12 @@ import {
 } from '../transformers/index.mjs'
 
 /**
- * @template {import('../../types.js').MongoDocument} T
- * @template {import('../../types.js').Projection<T>} K
+ * @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]
+ * @param {import('../../../types.js').FindOptions<T, K>} [parameter.options]
  * @returns {Promise<T[]>}
  */
 export async function find({ getCollection, query, options }) {

package/src/usecases/{operation → mongo/operation}/find_one.mjs

@@ -2,11 +2,11 @@ import { Collection } from 'mongodb'
 import { find } from './find.mjs'
 
 /**
- * @template {import('../../types.js').MongoDocument} T
- * @template {import('../../types.js').Projection<T> | undefined} K
+ * @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 {import('../../../types.js').FindOptions<T, K>} [param.options]
  * @param {() => Promise<Collection<T>>} param.getCollection
  */
 export async function findOne({ query, options, getCollection }) {

package/src/usecases/{operation → mongo/operation}/insert_many.mjs

@@ -2,10 +2,11 @@ import { Collection, ObjectId } from 'mongodb'
 import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
 
 /**
- * @template {import('../../types.js').MongoDocument} T
+ * @template {import('../../../types.js').MongoDocument} T
  * @param {object} param
- * @param {import('../../types.js').Optional<T, 'id'>[]} param.docs
+ * @param {import('../../../types.js').Optional<T, 'id'>[]} param.docs
  * @param {() => Promise<Collection<T>>} param.getCollection
+ * @returns {Promise<T[]>}
  */
 export async function insertMany({ docs, getCollection }) {
     if (docs.length == 0) return []
@@ -26,5 +27,6 @@ export async function insertMany({ docs, getCollection }) {
             docs[index].id = id.toHexString()
         }
     }
+    // @ts-ignore
     return docs
 }

package/src/usecases/{operation → mongo/operation}/insert_one.mjs

@@ -2,11 +2,11 @@ import { Collection, ObjectId } from 'mongodb'
 import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
 
 /**
- * @template {import('../../types.js').MongoDocument} T
+ * @template {import('../../../types.js').MongoDocument} T
  * @param {object} param
- * @param {import('../../types.js').Optional<T, 'id'>} param.doc
+ * @param {import('../../../types.js').Optional<T, 'id'>} param.doc
  * @param {() => Promise<Collection<T>>} param.getCollection
- * @returns {Promise<Omit<T, 'id'> & {id: NonNullable<T['id']>;}>}
+ * @returns {Promise<T>}
  */
 export async function insertOne({ doc, getCollection }) {
     renameToMongoId(doc)
@@ -21,8 +21,7 @@ export async function insertOne({ doc, getCollection }) {
         // @ts-ignore
         id = id.toHexString()
     }
-    return {
-        id,
-        ...doc,
-    }
+
+    // @ts-ignore
+    return { id, ...doc }
 }

package/src/usecases/{operation → mongo/operation}/update_many.mjs

@@ -2,7 +2,7 @@ import { Collection } from 'mongodb'
 import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
 
 /**
- * @template {import('../../types.js').MongoDocument} T
+ * @template {import('../../../types.js').MongoDocument} T
  * @param {object} param
  * @param {import('mongodb').Filter<T>} param.query
  * @param {import('mongodb').UpdateFilter<T>} param.update

package/src/usecases/{operation → mongo/operation}/update_one.mjs

@@ -2,7 +2,7 @@ import { Collection } from 'mongodb'
 import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
 
 /**
- * @template {import('../../types.js').MongoDocument} T
+ * @template {import('../../../types.js').MongoDocument} T
  * @param {object} param
  * @param {import('mongodb').Filter<T>} param.query
  * @param {import('mongodb').UpdateFilter<T>} param.update

package/src/usecases/mongo/test/manage_mock_registry.mjs

@@ -0,0 +1,52 @@
+import { fakerPT_BR } from '@faker-js/faker'
+import { ObjectId } from 'mongodb'
+import { after, before } from 'node:test'
+import { generateNewId } from '../generate_new_id.mjs'
+import { closeClient } from '../mongo_client.mjs'
+import { deleteOne, insertOne } from '../operation/index.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 closeClient()
+    })
+
+    return {
+        id, name
+    }
+}

package/src/usecases/mongo/test/mock_get_collection.mjs

@@ -0,0 +1,21 @@
+import { Collection, ObjectId } from 'mongodb'
+import { getClient } from '../mongo_client.mjs'
+
+export async function mockGetCollection(collectionName = 'test') {
+    const client = await getClient()
+    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]
+ */

package/src/usecases/{transformers → mongo/transformers}/id/rename_find_options.mjs

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