assai 2.0.0 → 2.1.1

package/src/factories/create_mongo_collection.mjs

@@ -1,182 +1,225 @@
-import { Collection } from 'mongodb'
-import {
-    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.
- *
- * 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 {IcreateCollectionOptions<T>} [options]
- */
-export function createMongoCollection(name, options = {}) {
-
-    /** @type {Collection<T> | null} */
-    let _collection = null
-    const collectionOptions = options
-
-    async function getCollection() {
-        const {
-            connectionString, dbName, options: createOptions,
-            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 getClient({ connectionString })
-        let db = client.db(dbName, createOptions)
-        /** @type {Collection<T>} */
-        _collection = db.collection(name)
-        return _collection
-    }
-
-    return {
-        /**
-         * Returns the native driver.
-         */
-        getCollection,
-        /**
-         * @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
-         * @returns {Promise<T[]>}
-         */
-        find: async (query, options = {}) => {
-            return await find({ query, options, getCollection, collectionOptions })
-        },
-        /**
-         * @template {import('../types.js').Projection<T> | undefined} K
-         * @param {import('mongodb').Filter<T>} query
-         * @param {import('../types.js').FindOptions<T,K>} options
-         * @returns {Promise<T | null>}
-         */
-        findOne: async (query, options = {}) => {
-            return await findOne({ query, options, collectionOptions, getCollection })
-        },
-        /**
-         * @param {import('../types.js').Optional<T, 'id'>} doc
-         * @returns {Promise<T>}
-         */
-        insertOne: async (doc) => {
-            return await insertOne({
-                doc,
-                getCollection,
-                collectionOptions,
-            })
-        },
-        /**
-         *
-         * @param {import('../types.js').Optional<T, 'id'>[]} docs
-         * @returns {Promise<T[]>}
-         */
-        insertMany: async (docs) => await insertMany({ docs, collectionOptions, getCollection }),
-        /**
-         * @param {import('mongodb').Filter<T>} query
-         * @returns {Promise<boolean>}
-         */
-        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
-         * @param {import('mongodb').UpdateOptions} [options]
-         */
-        updateOne: async (query, update, options) => await updateOne({
-            query, update, options, collectionOptions, getCollection,
-        }),
-        /**
-         * @param {import('mongodb').Filter<T>} query
-         * @param {import('mongodb').UpdateFilter<T>} update
-         * @param {import('mongodb').UpdateOptions} [options]
-         */
-        updateMany: async (query, update, options) => await updateMany({
-            query, update, options, collectionOptions, getCollection,
-        })
-    }
-}
-
-/**
- * @template {import('../types.js').MongoDocument} T
- * @callback IcollectionGetter
- * @returns {Promise<Collection<T>>}
- */
-
-/**
- * @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`.
- *
- * Example:
- * ```js
- * collectionGetter: async () => await getMyCollection()
- * ```
- *
- * @property {IcollectionGetter<T>} [options.cachableCollectionGetter]
- * Same as `collectionGetter`. But the object is cached.
- *
- * Example:
- * ```js
- * cachableCollectionGetter: async () => await getMyCollection()
- * ```
- *
- * @property {string} [options.connectionString]
- * A custom connection string. If none is given, `process.env.DATABASE_URL` will be used.
- *
- * @property {string} [dbName] The name of the database.
- *
- * @property {import('mongodb').DbOptions} [options] The options used when initializing the client.
- *
- * @property {ItimestampConfiguration} [timestamps]
- */
-
-/**
- * @typedef {object} ItimestampConfiguration
- * @property {'fromId' | 'generate' | 'none'} createdAt
- * @property {'generate' | 'none'} updatedAt
- */
-
-/**
- * @template {import('../types.js').MongoDocument} T
- * @typedef {Awaited<ReturnType<typeof createMongoCollection<T>>>} ICollection
+import { Collection } from 'mongodb'
+import {
+    aggregate, bulkWrite,
+    count, deleteMany, deleteOne,
+    deleteOneOrThrow,
+    find, findOne, findOneAndDelete, findOneAndReplace, findOneAndUpdate,
+    getClient,
+    insertMany, insertOne, updateMany, updateOne
+} from '../usecases/mongo/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` to customize this behavior.
+ * @template {import('../types.js').MongoDocument} T
+ * @param {string} name
+ * @param {IcreateCollectionOptions<T>} [options]
+ */
+export function createMongoCollection(name, options = {}) {
+
+    /** @type {Collection<T> | null} */
+    let _collection = null
+    const collectionOptions = options
+
+    async function getCollection() {
+        const {
+            connectionString, dbName, options: createOptions,
+            collectionGetter,
+        } = options
+
+        // Connection getter from options
+        if (collectionGetter != null) return await collectionGetter()
+
+        // Checking cache
+        if (_collection) return _collection
+
+        // Default connection getter
+        const client = await getClient({ connectionString })
+        let db = client.db(dbName, createOptions)
+        /** @type {Collection<T>} */
+        _collection = db.collection(name)
+        return _collection
+    }
+
+    return {
+        /**
+         * Returns the native driver.
+         */
+        getCollection,
+        /**
+         * @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
+         * @returns {Promise<T[]>}
+         */
+        find: async (query, options = {}) => {
+            return await find({ query, options, getCollection, collectionOptions })
+        },
+        /**
+         * @template {import('../types.js').Projection<T> | undefined} K
+         * @param {import('mongodb').Filter<T>} query
+         * @param {import('../types.js').FindOptions<T,K>} options
+         * @returns {Promise<T | null>}
+         */
+        findOne: async (query, options = {}) => {
+            return await findOne({ query, options, collectionOptions, getCollection })
+        },
+        /**
+         * @param {import('../types.js').Optional<T, 'id'>} doc
+         * @returns {Promise<T>}
+         */
+        insertOne: async (doc) => {
+            return await insertOne({
+                doc,
+                getCollection,
+                collectionOptions,
+            })
+        },
+        /**
+         *
+         * @param {import('../types.js').Optional<T, 'id'>[]} docs
+         * @returns {Promise<T[]>}
+         */
+        insertMany: async (docs) => await insertMany({ docs, collectionOptions, getCollection }),
+        /**
+         * @param {import('mongodb').Filter<T>} query
+         * @returns {Promise<boolean>}
+         */
+        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
+         * @param {import('mongodb').UpdateOptions} [options]
+         */
+        updateOne: async (query, update, options) => await updateOne({
+            query, update, options, collectionOptions, getCollection,
+        }),
+        /**
+         * @param {import('mongodb').Filter<T>} query
+         * @param {import('mongodb').UpdateFilter<T>} update
+         * @param {import('mongodb').UpdateOptions} [options]
+         */
+        updateMany: async (query, update, options) => await updateMany({
+            query, update, options, collectionOptions, getCollection,
+        }),
+        /**
+         * @param {import('mongodb').Document[]} pipeline
+         * @param {import('mongodb').AggregateOptions} [options]
+         * @returns {Promise<T[]>}
+         */
+        aggregate: async (pipeline, options) => await aggregate({
+            pipeline, options, getCollection, collectionOptions,
+        }),
+        /**
+         * @param {import('mongodb').AnyBulkWriteOperation<T>[]} operations
+         * @param {import('mongodb').BulkWriteOptions} [options]
+         */
+        bulkWrite: async (operations, options) => await bulkWrite({
+            operations, options, getCollection, collectionOptions,
+        }),
+        /**
+         * Atomically finds a document, applies the update, and returns the document.
+         * By default returns the document as it was **before** the update.
+         * Pass `{ returnDocument: 'after' }` in options to get the updated version.
+         * @param {import('mongodb').Filter<T>} query
+         * @param {import('mongodb').UpdateFilter<T>} update
+         * @param {import('mongodb').FindOneAndUpdateOptions} [options]
+         * @returns {Promise<T | null>}
+         */
+        findOneAndUpdate: async (query, update, options) => await findOneAndUpdate({
+            query, update, options, getCollection, collectionOptions,
+        }),
+        /**
+         * Atomically finds a document, deletes it, and returns the deleted document.
+         * @param {import('mongodb').Filter<T>} query
+         * @param {import('mongodb').FindOneAndDeleteOptions} [options]
+         * @returns {Promise<T | null>}
+         */
+        findOneAndDelete: async (query, options) => await findOneAndDelete({
+            query, options, getCollection, collectionOptions,
+        }),
+        /**
+         * Atomically finds a document, replaces it with `replacement`, and returns a document.
+         * By default returns the document as it was **before** the replacement.
+         * Pass `{ returnDocument: 'after' }` in options to get the new version.
+         * @param {import('mongodb').Filter<T>} query
+         * @param {import('mongodb').WithoutId<T>} replacement
+         * @param {import('mongodb').FindOneAndReplaceOptions} [options]
+         * @returns {Promise<T | null>}
+         */
+        findOneAndReplace: async (query, replacement, options) => await findOneAndReplace({
+            query, replacement, options, getCollection, collectionOptions,
+        }),
+    }
+}
+
+/**
+ * @template {import('../types.js').MongoDocument} T
+ * @callback IcollectionGetter
+ * @returns {Promise<Collection<T>>}
+ */
+
+/**
+ * @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`.
+ *
+ * Example:
+ * ```js
+ * collectionGetter: async () => await getMyCollection()
+ * ```
+ *
+ * @property {string} [options.connectionString]
+ * A custom connection string. If none is given, `process.env.DATABASE_URL` will be used.
+ *
+ * @property {string} [dbName] The name of the database.
+ *
+ * @property {import('mongodb').DbOptions} [options] The options used when initializing the client.
+ *
+ * @property {ItimestampConfiguration} [timestamps] Configured how the package manages 'createdAt'
+ * and 'updatedAt'.
+ */
+
+/**
+ * @typedef {object} ItimestampConfiguration
+ * @property {'fromId' | 'generate' | 'none'} createdAt
+ * Changes how the 'createdAt' field is managed:
+ * - 'fromId': the field is generated when you use `find` or `findOne` and is calculated using _id.
+ * But it does not exist in the database.
+ * - 'generate': the field is generated when you use `insertOne` or `insertMany`. The value exist in
+ * the database.
+ * - 'none': no value is generated at any time.
+ * @property {'generate' | 'none'} updatedAt
+ * - 'generate': the value is generated when you use `insertOne` or `insertMany` and is updated on
+ * `updateOne` and `updateMany`.
+ */
+
+/**
+ * @template {import('../types.js').MongoDocument} T
+ * @typedef {Awaited<ReturnType<typeof createMongoCollection<T>>>} ICollection
  */

package/src/factories/index.mjs

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

package/src/types.ts

@@ -1,32 +1,32 @@
-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
-}
-
-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
-
-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 FindOptions<T extends MongoDocument, K extends Projection<T>> = Omit<FO, 'projection'> & {
-    projection?: K
+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
+}
+
+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
+
+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 FindOptions<T extends MongoDocument, K extends Projection<T>> = Omit<FO, 'projection'> & {
+    projection?: K
 }

package/src/usecases/index.mjs

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

package/src/usecases/mongo/generate_new_id.mjs

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

package/src/usecases/mongo/index.mjs

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

package/src/usecases/mongo/mongo_client.mjs

@@ -1,37 +1,37 @@
-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 getClient({
-    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 closeClient() {
-    if (client == null) {
-        return false
-    }
-    await client?.close()
-    client = null
-    return true
+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 getClient({
+    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 closeClient() {
+    if (client == null) {
+        return false
+    }
+    await client?.close()
+    client = null
+    return true
 }

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

@@ -1,18 +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')
-    }
+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/mongo/operation/additional/index.mjs

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

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

@@ -0,0 +1,21 @@
+import { Collection } from 'mongodb'
+import { renameToMongoId, stringsIntoId } from '../transformers/index.mjs'
+import { outputTransformer } from '../transformers/output_transformer.mjs'
+
+/**
+ * @template {import('../../../types.js').MongoDocument} T
+ * @param {object} parameter
+ * @param {() => Promise<Collection<T>>} parameter.getCollection
+ * @param {import('mongodb').Document[]} parameter.pipeline
+ * @param {import('mongodb').AggregateOptions} [parameter.options]
+ * @param {import('../../../factories/create_mongo_collection.mjs').IcreateCollectionOptions<T>} [parameter.collectionOptions]
+ * @returns {Promise<T[]>}
+ */
+export async function aggregate({ getCollection, pipeline, options, collectionOptions }) {
+    const finalPipeline = stringsIntoId(renameToMongoId(pipeline))
+
+    const col = await getCollection()
+    const docs = await col.aggregate(finalPipeline, options).toArray()
+    // @ts-ignore
+    return docs.map((doc) => outputTransformer({ document: doc, collectionOptions }))
+}