albatross 3.4.2 → 3.7.0

package/index.d.ts

@@ -10,6 +10,26 @@ 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 }
 
+interface FindOneOptions<T> extends Omit<mongodb.FindOneOptions<T>, 'hint'> {
+  hint?: string | object
+}
+
+interface FindOneAndUpdateOption<T> extends Omit<mongodb.FindOneAndUpdateOption<T>, 'hint'> {
+  hint?: string | object
+}
+
+interface UpdateOneOptions extends Omit<mongodb.UpdateOneOptions, 'hint'> {
+  hint?: string | object
+}
+
+interface UpdateManyOptions extends Omit<mongodb.UpdateManyOptions, 'hint'> {
+  hint?: string | object
+}
+
+interface FindOneAndDeleteOption<T> extends Omit<mongodb.FindOneAndDeleteOption<T>, 'hint'> {
+  hint?: string | object
+}
+
 declare function albatross (uri: string): albatross.Albatross
 
 declare namespace albatross {
@@ -17,45 +37,52 @@ declare namespace albatross {
     readonly parent: Albatross
     id (hexString?: mongodb.ObjectId | string): mongodb.ObjectId
 
-    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>
+    findOne (filter: mongodb.FilterQuery<TSchema>, options?: WithoutProjection<FindOneOptions<TSchema>>): Promise<TSchema | null>
+    findOne<TKey extends keyof TSchema> (filter: mongodb.FilterQuery<TSchema>, options: SpecificProjection<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<FindOneOptions<TSchema>, { [key in TKey]: 1 | true } & { _id?: 1 | true }>): Promise<Pick<TSchema, '_id' | TKey> | null>
+    findOne (filter: mongodb.FilterQuery<TSchema>, options: 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[]>
+    find (query: mongodb.FilterQuery<TSchema>, options?: WithoutProjection<FindOneOptions<TSchema>>): Promise<TSchema[]>
+    find<TKey extends keyof TSchema> (query: mongodb.FilterQuery<TSchema>, options: SpecificProjection<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<FindOneOptions<TSchema>, { [key in TKey]: 1 | true } & { _id?: 1 | true }>): Promise<Array<Pick<TSchema, '_id' | TKey>>>
+    find (query: mongodb.FilterQuery<TSchema>, options: FindOneOptions<TSchema>): Promise<object[]>
 
     count (query?: mongodb.FilterQuery<TSchema>, options?: mongodb.MongoCountPreferences): Promise<number>
 
     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>
+    exists (query?: mongodb.FilterQuery<TSchema>, options?: { hint?: string | object }): Promise<boolean>
 
     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 (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options: WithoutProjection<FindOneAndUpdateOption<TSchema> & { returnOriginal: false, upsert: true }>): Promise<TSchema>
+    findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: WithoutProjection<FindOneAndUpdateOption<TSchema>>): Promise<TSchema | null>
+
+    findOneAndUpdate<TKey extends keyof TSchema> (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options: SpecificProjection<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<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: 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<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<FindOneAndUpdateOption<TSchema>, { [key in TKey]: 1 | true } & { _id?: 1 | true }>): Promise<Pick<TSchema, '_id' | 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: FindOneAndUpdateOption<TSchema> & { returnOriginal: false, upsert: true }): Promise<object>
+    findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: FindOneAndUpdateOption<TSchema>): Promise<object | 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?: UpdateOneOptions): Promise<{ matched: 0 | 1, modified: 0 | 1 }>
+    updateMany (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: UpdateManyOptions): Promise<{ matched: number, modified: number }>
 
-    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 }>
+    deleteOne (filter: mongodb.FilterQuery<TSchema>, options?: mongodb.CommonOptions & { bypassDocumentValidation?: boolean, hint?: string | object }): Promise<0 | 1>
+    deleteMany (filter: mongodb.FilterQuery<TSchema>, options?: mongodb.CommonOptions & { hint?: string | object }): Promise<number>
 
-    deleteOne (filter: mongodb.FilterQuery<TSchema>, options?: mongodb.CommonOptions & { bypassDocumentValidation?: boolean }): Promise<0 | 1>
-    deleteMany (filter: mongodb.FilterQuery<TSchema>, options?: mongodb.CommonOptions): Promise<number>
+    findOneAndDelete (filter: mongodb.FilterQuery<TSchema>, options?: WithoutProjection<FindOneAndDeleteOption<TSchema>>): Promise<TSchema | null>
+    findOneAndDelete<TKey extends keyof TSchema> (filter: mongodb.FilterQuery<TSchema>, options: SpecificProjection<FindOneAndDeleteOption<TSchema>, { [key in TKey]: 1 | true } & { _id: 0 | false }>): Promise<Pick<TSchema, TKey> | null>
+    findOneAndDelete<TKey extends keyof TSchema> (filter: mongodb.FilterQuery<TSchema>, options: SpecificProjection<FindOneAndDeleteOption<TSchema>, { [key in TKey]: 1 | true } & { _id?: 1 | true }>): Promise<Pick<TSchema, '_id' | TKey> | null>
+    findOneAndDelete (filter: mongodb.FilterQuery<TSchema>, options?: FindOneAndDeleteOption<TSchema>): Promise<object | null>
 
     aggregate (pipeline: object[], options?: mongodb.CollectionAggregationOptions): Promise<object[]>
+
+    createIndex (fieldOrSpec: string | any, options?: mongodb.IndexOptions): Promise<string>
   }
 
   interface FileInfo {
@@ -82,6 +109,7 @@ declare namespace albatross {
     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/lib/collection.js

@@ -76,12 +76,16 @@ class Collection {
     }
   }
 
-  async exists (query) {
+  async exists (query, opts) {
     const db = await this.parent.db()
 
     // https://blog.serverdensity.com/checking-if-a-document-exists-mongodb-slow-findone-vs-find/
     const cursor = db.collection(this.name).find(query, { projection: { _id: 1 }, limit: 1 })
 
+    if (opts && opts.hint) {
+      cursor.hint(opts.hint)
+    }
+
     try {
       this[kDebug]('exists(%o)', query)
       const res = await cursor.hasNext()
@@ -186,6 +190,20 @@ class Collection {
     }
   }
 
+  async findOneAndDelete (filter, opts) {
+    const db = await this.parent.db()
+
+    try {
+      this[kDebug]('findOneAndDelete(%o)', filter)
+      const res = await db.collection(this.name).findOneAndDelete(filter, opts)
+      this[kDebug](`reply OK ${res.value == null ? 0 : 1}`)
+      return res.value
+    } catch (err) {
+      this[kDebug]('reply ERR')
+      throw err
+    }
+  }
+
   async aggregate (pipeline, opts) {
     const db = await this.parent.db()
 
@@ -199,6 +217,20 @@ class Collection {
       throw err
     }
   }
+
+  async createIndex (fieldOrSpec, opts) {
+    const db = await this.parent.db()
+
+    try {
+      this[kDebug]('createIndex(%o, %o)', fieldOrSpec, opts)
+      const res = await db.collection(this.name).createIndex(fieldOrSpec, opts)
+      this[kDebug]('reply OK')
+      return res
+    } catch (err) {
+      this[kDebug]('reply ERR')
+      throw err
+    }
+  }
 }
 
 module.exports = Collection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "albatross",
-  "version": "3.4.2",
+  "version": "3.7.0",
   "license": "MIT",
   "author": "Linus Unnebäck <linus@folkdatorn.se>",
   "repository": "LinusU/node-albatross",

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.
@@ -165,6 +185,10 @@ Deletes a single document matching `filter`. Resolves with the number of documen
 
 Deletes multiple documents matching `filter`. Resolves with the number of documents deleted.
 
+#### `findOneAndDelete(filter[, opts]): Promise<object>`
+
+Finds a document and deletes it in one atomic operation.
+
 #### `aggregate(pipeline[, opts]): Promise<object[]>`
 
 Executes an aggregation framework pipeline against the collection. Resolves with the aggregated objects.