assai 2.0.0 → 2.1.0

package/README.md

@@ -1,148 +1,148 @@
-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 { createMongoCollection } from 'assai'
-
-/** @type {import('assai').ICollection<user>} */
-const collection = await createMongoCollection()
-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 `generateNewId` method:
-
-```js
-import { mongo } from 'assai'
-
-const myStringId = mongo.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 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 createMongoCollection('myCollection')
-```
-
-This will read the value from `process.env.DATABASE_URL`.
-
-You can still pass a custom connection string:
-
-```js
-const database = await createMongoCollection('myCollection', {
-  connectionString: '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.connect('...')
-        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')
-    await col.insertOne({
-        name: req.body.name,
-    })
-})
-```
-
-You can simply write:
-
-```js
-router.post('/', (req, res) => {
-    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 col.insertOne({
-        name: req.body.name,
-    })
-    // ...
-})
-```
+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 { createMongoCollection } from 'assai'
+
+/** @type {import('assai').ICollection<user>} */
+const collection = await createMongoCollection()
+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 `generateNewId` method:
+
+```js
+import { mongo } from 'assai'
+
+const myStringId = mongo.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 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 createMongoCollection('myCollection')
+```
+
+This will read the value from `process.env.DATABASE_URL`.
+
+You can still pass a custom connection string:
+
+```js
+const database = await createMongoCollection('myCollection', {
+  connectionString: '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.connect('...')
+        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')
+    await col.insertOne({
+        name: req.body.name,
+    })
+})
+```
+
+You can simply write:
+
+```js
+router.post('/', (req, res) => {
+    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 col.insertOne({
+        name: req.body.name,
+    })
+    // ...
+})
+```

package/dist/src/factories/create_mongo_collection.d.mts

@@ -4,8 +4,7 @@
  * 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.
+ * 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]
@@ -73,6 +72,44 @@ export function createMongoCollection<T extends import("../types.js").MongoDocum
      * @param {import('mongodb').UpdateOptions} [options]
      */
     updateMany: (query: import("mongodb").Filter<T>, update: import("mongodb").UpdateFilter<T>, options?: import("mongodb").UpdateOptions | undefined) => Promise<import("mongodb").UpdateResult<T>>;
+    /**
+     * @param {import('mongodb').Document[]} pipeline
+     * @param {import('mongodb').AggregateOptions} [options]
+     * @returns {Promise<T[]>}
+     */
+    aggregate: (pipeline: import('mongodb').Document[], options?: import("mongodb").AggregateOptions | undefined) => Promise<T[]>;
+    /**
+     * @param {import('mongodb').AnyBulkWriteOperation<T>[]} operations
+     * @param {import('mongodb').BulkWriteOptions} [options]
+     */
+    bulkWrite: (operations: import("mongodb").AnyBulkWriteOperation<T>[], options?: import("mongodb").BulkWriteOptions | undefined) => Promise<import("mongodb").BulkWriteResult>;
+    /**
+     * 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: (query: import("mongodb").Filter<T>, update: import("mongodb").UpdateFilter<T>, options?: import("mongodb").FindOneAndUpdateOptions | undefined) => Promise<T | null>;
+    /**
+     * 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: (query: import("mongodb").Filter<T>, options?: import("mongodb").FindOneAndDeleteOptions | undefined) => Promise<T | null>;
+    /**
+     * 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: (query: import("mongodb").Filter<T>, replacement: import("mongodb").WithoutId<T>, options?: import("mongodb").FindOneAndReplaceOptions | undefined) => Promise<T | null>;
 };
 export type IcollectionGetter<T extends import("../types.js").MongoDocument> = () => Promise<Collection<T>>;
 export type IcreateCollectionOptions<T extends import("../types.js").MongoDocument> = {
@@ -89,15 +126,6 @@ export type IcreateCollectionOptions<T extends import("../types.js").MongoDocume
      * ```
      */
     collectionGetter?: IcollectionGetter<T> | undefined;
-    /**
-     * Same as `collectionGetter`. But the object is cached.
-     *
-     * Example:
-     * ```js
-     * cachableCollectionGetter: async () => await getMyCollection()
-     * ```
-     */
-    cachableCollectionGetter?: IcollectionGetter<T> | undefined;
     /**
      * A custom connection string. If none is given, `process.env.DATABASE_URL` will be used.
      */
@@ -110,10 +138,26 @@ export type IcreateCollectionOptions<T extends import("../types.js").MongoDocume
      * The options used when initializing the client.
      */
     options?: import("mongodb").DbOptions | undefined;
+    /**
+     * Configured how the package manages 'createdAt'
+     * and 'updatedAt'.
+     */
     timestamps?: ItimestampConfiguration | undefined;
 };
 export type ItimestampConfiguration = {
+    /**
+     * 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.
+     */
     createdAt: 'fromId' | 'generate' | 'none';
+    /**
+     * - 'generate': the value is generated when you use `insertOne` or `insertMany` and is updated on
+     * `updateOne` and `updateMany`.
+     */
     updatedAt: 'generate' | 'none';
 };
 export type ICollection<T extends import("../types.js").MongoDocument> = Awaited<ReturnType<typeof createMongoCollection<T>>>;

package/dist/src/usecases/mongo/operation/aggregate.d.mts

@@ -0,0 +1,16 @@
+/**
+ * @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 function aggregate<T extends import("../../../types.js").MongoDocument>({ getCollection, pipeline, options, collectionOptions }: {
+    getCollection: () => Promise<Collection<T>>;
+    pipeline: import('mongodb').Document[];
+    options?: import("mongodb").AggregateOptions | undefined;
+    collectionOptions?: import("../../../factories/create_mongo_collection.mjs").IcreateCollectionOptions<T> | undefined;
+}): Promise<T[]>;
+import { Collection } from 'mongodb';

package/dist/src/usecases/mongo/operation/bulk_write.d.mts

@@ -0,0 +1,15 @@
+/**
+ * @template {import('../../../types.js').MongoDocument} T
+ * @param {object} parameter
+ * @param {() => Promise<Collection<T>>} parameter.getCollection
+ * @param {import('mongodb').AnyBulkWriteOperation<T>[]} parameter.operations
+ * @param {import('mongodb').BulkWriteOptions} [parameter.options]
+ * @param {import('../../../factories/create_mongo_collection.mjs').IcreateCollectionOptions<T>} [parameter.collectionOptions]
+ */
+export function bulkWrite<T extends import("../../../types.js").MongoDocument>({ getCollection, operations, options, collectionOptions }: {
+    getCollection: () => Promise<Collection<T>>;
+    operations: import("mongodb").AnyBulkWriteOperation<T>[];
+    options?: import("mongodb").BulkWriteOptions | undefined;
+    collectionOptions?: import("../../../factories/create_mongo_collection.mjs").IcreateCollectionOptions<T> | undefined;
+}): Promise<import("mongodb").BulkWriteResult>;
+import { Collection } from 'mongodb';

package/dist/src/usecases/mongo/operation/find_one_and_delete.d.mts

@@ -0,0 +1,16 @@
+/**
+ * @template {import('../../../types.js').MongoDocument} T
+ * @param {object} param
+ * @param {import('mongodb').Filter<T>} param.query
+ * @param {import('mongodb').FindOneAndDeleteOptions} [param.options]
+ * @param {() => Promise<Collection<T>>} param.getCollection
+ * @param {import('../../../factories/create_mongo_collection.mjs').IcreateCollectionOptions<T>} [param.collectionOptions]
+ * @returns {Promise<T | null>}
+ */
+export function findOneAndDelete<T extends import("../../../types.js").MongoDocument>({ query, options, collectionOptions, getCollection }: {
+    query: import("mongodb").Filter<T>;
+    options?: import("mongodb").FindOneAndDeleteOptions | undefined;
+    getCollection: () => Promise<Collection<T>>;
+    collectionOptions?: import("../../../factories/create_mongo_collection.mjs").IcreateCollectionOptions<T> | undefined;
+}): Promise<T | null>;
+import { Collection } from 'mongodb';

package/dist/src/usecases/mongo/operation/find_one_and_replace.d.mts

@@ -0,0 +1,18 @@
+/**
+ * @template {import('../../../types.js').MongoDocument} T
+ * @param {object} param
+ * @param {import('mongodb').Filter<T>} param.query
+ * @param {import('mongodb').WithoutId<T>} param.replacement
+ * @param {import('mongodb').FindOneAndReplaceOptions} [param.options]
+ * @param {() => Promise<Collection<T>>} param.getCollection
+ * @param {import('../../../factories/create_mongo_collection.mjs').IcreateCollectionOptions<T>} [param.collectionOptions]
+ * @returns {Promise<T | null>}
+ */
+export function findOneAndReplace<T extends import("../../../types.js").MongoDocument>({ query, replacement, options, collectionOptions, getCollection }: {
+    query: import("mongodb").Filter<T>;
+    replacement: import("mongodb").WithoutId<T>;
+    options?: import("mongodb").FindOneAndReplaceOptions | undefined;
+    getCollection: () => Promise<Collection<T>>;
+    collectionOptions?: import("../../../factories/create_mongo_collection.mjs").IcreateCollectionOptions<T> | undefined;
+}): Promise<T | null>;
+import { Collection } from 'mongodb';

package/dist/src/usecases/mongo/operation/find_one_and_update.d.mts

@@ -0,0 +1,18 @@
+/**
+ * @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').FindOneAndUpdateOptions} [param.options]
+ * @param {() => Promise<Collection<T>>} param.getCollection
+ * @param {import('../../../factories/create_mongo_collection.mjs').IcreateCollectionOptions<T>} [param.collectionOptions]
+ * @returns {Promise<T | null>}
+ */
+export function findOneAndUpdate<T extends import("../../../types.js").MongoDocument>({ query, update, options, collectionOptions, getCollection }: {
+    query: import("mongodb").Filter<T>;
+    update: import("mongodb").UpdateFilter<T>;
+    options?: import("mongodb").FindOneAndUpdateOptions | undefined;
+    getCollection: () => Promise<Collection<T>>;
+    collectionOptions?: import("../../../factories/create_mongo_collection.mjs").IcreateCollectionOptions<T> | undefined;
+}): Promise<T | null>;
+import { Collection } from 'mongodb';

package/dist/src/usecases/mongo/operation/index.d.mts

@@ -1,9 +1,14 @@
 export * from "./additional/index.mjs";
+export * from "./aggregate.mjs";
+export * from "./bulk_write.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 "./find_one_and_delete.mjs";
+export * from "./find_one_and_replace.mjs";
+export * from "./find_one_and_update.mjs";
 export * from "./insert_many.mjs";
 export * from "./insert_one.mjs";
 export * from "./update_many.mjs";

package/index.mjs

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

package/jsconfig.json

@@ -1,20 +1,17 @@
-{
-    "compilerOptions": {
-        "allowJs": true,
-        "checkJs": true,
-        "strictNullChecks": true,
-        "module": "ES2022",
-        "target": "ES2022",
-        "moduleResolution": "node",
-        "sourceMap": true,
-        "declaration": true,
-        "strictPropertyInitialization": true,
-        "lib": [
-            "ES2022"
-        ],
-        "baseUrl": "./",
-        "noEmit": false,
-        "emitDeclarationOnly": true,
-        "outDir": "dist"
-    },
-}
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "strictNullChecks": true,
+    "module": "nodenext",
+    "target": "ES2022",
+    "moduleResolution": "nodenext",
+    "sourceMap": true,
+    "declaration": true,
+    "strictPropertyInitialization": true,
+    "lib": ["ES2022"],
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "outDir": "dist"
+  }
+}

package/jsconfig.prod.json

@@ -1,13 +1,13 @@
-{
-    "extends": "./jsconfig.json",
-    "include": [
-        "./src/**/*.mjs",
-        "./index.mjs"
-    ],
-    "exclude": [
-        "dist",
-        "test/**/*",
-        "src/**/*.test.mjs",
-        "node_modules"
-    ]
+{
+    "extends": "./jsconfig.json",
+    "include": [
+        "./src/**/*.mjs",
+        "./index.mjs"
+    ],
+    "exclude": [
+        "dist",
+        "test/**/*",
+        "src/**/*.test.mjs",
+        "node_modules"
+    ]
 }

package/package.json

@@ -1,39 +1,40 @@
-{
-  "name": "assai",
-  "version": "2.0.0",
-  "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",
-  "types": "dist/index.d.mts",
-  "scripts": {
-    "prepare": "rm -rf dist && tsc -p ./jsconfig.prod.json",
-    "start": "node --env-file=.env index.mjs",
-    "test": "node --test"
-  },
-  "keywords": [
-    "mongodb",
-    "orm"
-  ],
-  "files": [
-    "index.mjs",
-    "src/",
-    "dist",
-    "!src/**/*.test.mjs",
-    "jsconfig.json",
-    "jsconfig.prod.json"
-  ],
-  "author": "Vinícius Gabriel",
-  "license": "ISC",
-  "dependencies": {
-    "mongodb": "^7.0.0"
-  },
-  "devDependencies": {
-    "@faker-js/faker": "^8.4.1",
-    "@types/node": "^20.12.7",
-    "mongodb-memory-server": "^10.0.0",
-    "typescript": "^5.4.5"
-  }
-}
+{
+  "name": "assai",
+  "version": "2.1.0",
+  "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",
+  "types": "dist/index.d.mts",
+  "scripts": {
+    "prepare": "rm -rf dist && tsc -p ./jsconfig.prod.json",
+    "start": "node --env-file=.env index.mjs",
+    "test": "node --test",
+    "check": "tsc -p jsconfig.json"
+  },
+  "keywords": [
+    "mongodb",
+    "orm"
+  ],
+  "files": [
+    "index.mjs",
+    "src/",
+    "dist",
+    "!src/**/*.test.mjs",
+    "jsconfig.json",
+    "jsconfig.prod.json"
+  ],
+  "author": "Vinícius Gabriel",
+  "license": "ISC",
+  "dependencies": {
+    "mongodb": "^7.0.0"
+  },
+  "devDependencies": {
+    "@faker-js/faker": "^8.4.1",
+    "@types/node": "^20.12.7",
+    "mongodb-memory-server": "^10.0.0",
+    "typescript": "^5.4.5"
+  }
+}