albatross 3.3.0 → 3.5.0

package/index.d.ts

@@ -1,29 +1,53 @@
 import * as mongodb from 'mongodb'
 
+type DeepReadonly<T> = T extends Date | RegExp | string | number | boolean | bigint | symbol | undefined | null
+  ? T
+  : T extends {}
+  ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
+  : Readonly<T>
+
 type FlattenIfArray<T> = T extends Array<infer R> ? R : T
+type SpecificProjection<T, TProjection> = Omit<T, 'projection'> & { projection: TProjection }
+type WithoutProjection<T> = T & { fields?: undefined, projection?: undefined }
 
 declare function albatross (uri: string): albatross.Albatross
 
 declare namespace albatross {
-  interface Collection<TSchema = any> {
+  interface Collection<TSchema extends { _id: any }> {
     readonly parent: Albatross
     id (hexString?: mongodb.ObjectId | string): mongodb.ObjectId
 
-    findOne<T = TSchema> (filter: mongodb.FilterQuery<TSchema>, options?: mongodb.FindOneOptions): Promise<T | null>
-    find<T = TSchema> (query: mongodb.FilterQuery<TSchema>, options?: mongodb.FindOneOptions): Promise<T[]>
+    findOne (filter: mongodb.FilterQuery<TSchema>, options?: WithoutProjection<mongodb.FindOneOptions<TSchema>>): Promise<TSchema | null>
+    findOne<TKey extends keyof TSchema> (filter: mongodb.FilterQuery<TSchema>, options: SpecificProjection<mongodb.FindOneOptions<TSchema>, { [key in TKey]: 1 | true } & { _id: 0 | false }>): Promise<Pick<TSchema, TKey> | null>
+    findOne<TKey extends keyof TSchema> (filter: mongodb.FilterQuery<TSchema>, options: SpecificProjection<mongodb.FindOneOptions<TSchema>, { [key in TKey]: 1 | true } & { _id?: 1 | true }>): Promise<Pick<TSchema, '_id' | TKey> | null>
+    findOne (filter: mongodb.FilterQuery<TSchema>, options: mongodb.FindOneOptions<TSchema>): Promise<object | null>
+
+    find (query: mongodb.FilterQuery<TSchema>, options?: WithoutProjection<mongodb.FindOneOptions<TSchema>>): Promise<TSchema[]>
+    find<TKey extends keyof TSchema> (query: mongodb.FilterQuery<TSchema>, options: SpecificProjection<mongodb.FindOneOptions<TSchema>, { [key in TKey]: 1 | true } & { _id: 0 | false }>): Promise<Array<Pick<TSchema, TKey>>>
+    find<TKey extends keyof TSchema> (query: mongodb.FilterQuery<TSchema>, options: SpecificProjection<mongodb.FindOneOptions<TSchema>, { [key in TKey]: 1 | true } & { _id?: 1 | true }>): Promise<Array<Pick<TSchema, '_id' | TKey>>>
+    find (query: mongodb.FilterQuery<TSchema>, options: mongodb.FindOneOptions<TSchema>): Promise<object[]>
 
     count (query?: mongodb.FilterQuery<TSchema>, options?: mongodb.MongoCountPreferences): Promise<number>
 
-    distinct<Key extends keyof mongodb.WithId<TSchema>> (key: Key, query?: mongodb.FilterQuery<TSchema>, options?: { readPreference?: mongodb.ReadPreference | string, maxTimeMS?: number, session?: mongodb.ClientSession }): Promise<Array<FlattenIfArray<mongodb.WithId<TSchema>[Key]>>>
+    distinct<TKey extends keyof mongodb.WithId<TSchema>> (key: TKey, query?: mongodb.FilterQuery<TSchema>, options?: { readPreference?: mongodb.ReadPreference | string, maxTimeMS?: number, session?: mongodb.ClientSession }): Promise<Array<FlattenIfArray<mongodb.WithId<TSchema>[TKey]>>>
     distinct (key: string, query?: mongodb.FilterQuery<TSchema>, options?: { readPreference?: mongodb.ReadPreference | string, maxTimeMS?: number, session?: mongodb.ClientSession }): Promise<any[]>
 
     exists (query?: mongodb.FilterQuery<TSchema>): Promise<boolean>
 
-    insert (doc: mongodb.OptionalId<TSchema>, options?: mongodb.CollectionInsertOneOptions): Promise<mongodb.WithId<TSchema>>
-    insert (docs: mongodb.OptionalId<TSchema>[], options?: mongodb.CollectionInsertManyOptions): Promise<mongodb.WithId<TSchema>[]>
+    insert (doc: DeepReadonly<mongodb.OptionalId<TSchema>>, options?: mongodb.CollectionInsertOneOptions): Promise<mongodb.WithId<TSchema>>
+    insert (docs: DeepReadonly<mongodb.OptionalId<TSchema>>[], options?: mongodb.CollectionInsertManyOptions): Promise<mongodb.WithId<TSchema>[]>
+
+    findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options: WithoutProjection<mongodb.FindOneAndUpdateOption<TSchema> & { returnOriginal: false, upsert: true }>): Promise<TSchema>
+    findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: WithoutProjection<mongodb.FindOneAndUpdateOption<TSchema>>): Promise<TSchema | null>
+
+    findOneAndUpdate<TKey extends keyof TSchema> (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options: SpecificProjection<mongodb.FindOneAndUpdateOption<TSchema> & { returnOriginal: false, upsert: true }, { [key in TKey]: 1 | true } & { _id: 0 | false }>): Promise<Pick<TSchema, TKey>>
+    findOneAndUpdate<TKey extends keyof TSchema> (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options: SpecificProjection<mongodb.FindOneAndUpdateOption<TSchema>, { [key in TKey]: 1 | true } & { _id: 0 | false }>): Promise<Pick<TSchema, TKey> | null>
+
+    findOneAndUpdate<TKey extends keyof TSchema> (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options: SpecificProjection<mongodb.FindOneAndUpdateOption<TSchema> & { returnOriginal: false, upsert: true }, { [key in TKey]: 1 | true } & { _id?: 1 | true }>): Promise<Pick<TSchema, '_id' | TKey>>
+    findOneAndUpdate<TKey extends keyof TSchema> (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options: SpecificProjection<mongodb.FindOneAndUpdateOption<TSchema>, { [key in TKey]: 1 | true } & { _id?: 1 | true }>): Promise<Pick<TSchema, '_id' | TKey> | null>
 
-    findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options: mongodb.FindOneAndUpdateOption & { returnOriginal: false, upsert: true }): Promise<TSchema>
-    findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: mongodb.FindOneAndUpdateOption): Promise<TSchema | null>
+    findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options: mongodb.FindOneAndUpdateOption<TSchema> & { returnOriginal: false, upsert: true }): Promise<object>
+    findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: mongodb.FindOneAndUpdateOption<TSchema>): Promise<object | null>
 
     updateOne (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: mongodb.UpdateOneOptions): Promise<{ matched: 0 | 1, modified: 0 | 1 }>
     updateMany (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: mongodb.UpdateManyOptions): Promise<{ matched: number, modified: number }>
@@ -31,7 +55,7 @@ declare namespace albatross {
     deleteOne (filter: mongodb.FilterQuery<TSchema>, options?: mongodb.CommonOptions & { bypassDocumentValidation?: boolean }): Promise<0 | 1>
     deleteMany (filter: mongodb.FilterQuery<TSchema>, options?: mongodb.CommonOptions): Promise<number>
 
-    aggregate<T = TSchema> (pipeline: object[], options?: mongodb.CollectionAggregationOptions): Promise<T[]>
+    aggregate (pipeline: object[], options?: mongodb.CollectionAggregationOptions): Promise<object[]>
   }
 
   interface FileInfo {
@@ -55,9 +79,10 @@ declare namespace albatross {
 
   interface Albatross {
     id (hexString?: mongodb.ObjectId | string): mongodb.ObjectId
-    collection<TSchema> (name: string): Collection<TSchema>
+    collection<TSchema extends { _id: any }> (name: string): Collection<TSchema>
     grid (name?: string): Grid
     ping (timeout?: number): Promise<void>
+    transaction<T> (fn: (session: mongodb.ClientSession) => PromiseLike<T>): Promise<T>
     close (force?: boolean): Promise<void>
   }
 

package/lib/albatross.js

@@ -99,6 +99,23 @@ class Albatross {
     }
   }
 
+  async transaction (fn) {
+    const client = await this[kConnect]()
+    const session = client.startSession()
+
+    let result
+
+    try {
+      await session.withTransaction(async (...args) => {
+        result = await fn(...args)
+      })
+    } finally {
+      session.endSession()
+    }
+
+    return result
+  }
+
   async close (force) {
     if (this[kClient] == null) return
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "albatross",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "license": "MIT",
   "author": "Linus Unnebäck <linus@folkdatorn.se>",
   "repository": "LinusU/node-albatross",
@@ -15,10 +15,10 @@
   },
   "dependencies": {
     "@types/bson": "1.0.11",
-    "@types/mongodb": "3.5.25",
-    "bson": "^1.1.1",
+    "@types/mongodb": "3.6.12",
+    "bson": "^1.1.4",
     "debug": "^4.1.1",
-    "mongodb": "^3.5.4"
+    "mongodb": "^3.6.0"
   },
   "devDependencies": {
     "@types/mocha": "^5.2.7",

package/readme.md

@@ -95,6 +95,26 @@ Send the `ping` command to the server, to check that the connection is still int
 
 Optionally accepts a timeout in milliseconds.
 
+#### `.transaction(fn): Promise`
+
+Runs a provided function within a transaction, retrying either the commit operation or entire transaction as needed (and when the error permits) to better ensure that the transaction can complete successfully.
+
+Example:
+
+```js
+const user = db.collection('user')
+
+const result = await db.transaction(async (session) => {
+    await user.insert({ name: 'Linus', born: 1992 }, { session })
+    await user.insert({ name: 'Steve', born: 1955 }, { session })
+
+    return await user.findOne({ born: 1992 }, { session })
+})
+
+console.log('Hello ' + result.name)
+//=> Hello Linus
+```
+
 #### `.close(): Promise<void>`
 
 Closes the connection to the server.