albatross 3.4.1 → 3.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/index.d.ts +48 -23
  2. package/lib/albatross.js +17 -0
  3. package/lib/collection.js +19 -1
  4. package/package.json +1 -1
  5. package/readme.md +20 -0
package/index.d.ts CHANGED
@@ -1,9 +1,31 @@
1
1
  import * as mongodb from 'mongodb'
2
2
 
3
+ type DeepReadonly<T> = T extends Date | RegExp | string | number | boolean | bigint | symbol | undefined | null
4
+ ? T
5
+ : T extends {}
6
+ ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
7
+ : Readonly<T>
8
+
3
9
  type FlattenIfArray<T> = T extends Array<infer R> ? R : T
4
10
  type SpecificProjection<T, TProjection> = Omit<T, 'projection'> & { projection: TProjection }
5
11
  type WithoutProjection<T> = T & { fields?: undefined, projection?: undefined }
6
12
 
13
+ interface FindOneOptions<T> extends Omit<mongodb.FindOneOptions<T>, 'hint'> {
14
+ hint?: string | object
15
+ }
16
+
17
+ interface FindOneAndUpdateOption<T> extends Omit<mongodb.FindOneAndUpdateOption<T>, 'hint'> {
18
+ hint?: string | object
19
+ }
20
+
21
+ interface UpdateOneOptions extends Omit<mongodb.UpdateOneOptions, 'hint'> {
22
+ hint?: string | object
23
+ }
24
+
25
+ interface UpdateManyOptions extends Omit<mongodb.UpdateManyOptions, 'hint'> {
26
+ hint?: string | object
27
+ }
28
+
7
29
  declare function albatross (uri: string): albatross.Albatross
8
30
 
9
31
  declare namespace albatross {
@@ -11,45 +33,47 @@ declare namespace albatross {
11
33
  readonly parent: Albatross
12
34
  id (hexString?: mongodb.ObjectId | string): mongodb.ObjectId
13
35
 
14
- findOne (filter: mongodb.FilterQuery<TSchema>, options?: WithoutProjection<mongodb.FindOneOptions<TSchema>>): Promise<TSchema | null>
15
- 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>
16
- 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>
17
- findOne (filter: mongodb.FilterQuery<TSchema>, options: mongodb.FindOneOptions<TSchema>): Promise<object | null>
36
+ findOne (filter: mongodb.FilterQuery<TSchema>, options?: WithoutProjection<FindOneOptions<TSchema>>): Promise<TSchema | null>
37
+ 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>
38
+ 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>
39
+ findOne (filter: mongodb.FilterQuery<TSchema>, options: FindOneOptions<TSchema>): Promise<object | null>
18
40
 
19
- find (query: mongodb.FilterQuery<TSchema>, options?: WithoutProjection<mongodb.FindOneOptions<TSchema>>): Promise<TSchema[]>
20
- 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>>>
21
- 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>>>
22
- find (query: mongodb.FilterQuery<TSchema>, options: mongodb.FindOneOptions<TSchema>): Promise<object[]>
41
+ find (query: mongodb.FilterQuery<TSchema>, options?: WithoutProjection<FindOneOptions<TSchema>>): Promise<TSchema[]>
42
+ 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>>>
43
+ 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>>>
44
+ find (query: mongodb.FilterQuery<TSchema>, options: FindOneOptions<TSchema>): Promise<object[]>
23
45
 
24
46
  count (query?: mongodb.FilterQuery<TSchema>, options?: mongodb.MongoCountPreferences): Promise<number>
25
47
 
26
48
  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]>>>
27
49
  distinct (key: string, query?: mongodb.FilterQuery<TSchema>, options?: { readPreference?: mongodb.ReadPreference | string, maxTimeMS?: number, session?: mongodb.ClientSession }): Promise<any[]>
28
50
 
29
- exists (query?: mongodb.FilterQuery<TSchema>): Promise<boolean>
51
+ exists (query?: mongodb.FilterQuery<TSchema>, options?: { hint?: string | object }): Promise<boolean>
30
52
 
31
- insert (doc: mongodb.OptionalId<TSchema>, options?: mongodb.CollectionInsertOneOptions): Promise<mongodb.WithId<TSchema>>
32
- insert (docs: mongodb.OptionalId<TSchema>[], options?: mongodb.CollectionInsertManyOptions): Promise<mongodb.WithId<TSchema>[]>
53
+ insert (doc: DeepReadonly<mongodb.OptionalId<TSchema>>, options?: mongodb.CollectionInsertOneOptions): Promise<mongodb.WithId<TSchema>>
54
+ insert (docs: DeepReadonly<mongodb.OptionalId<TSchema>>[], options?: mongodb.CollectionInsertManyOptions): Promise<mongodb.WithId<TSchema>[]>
33
55
 
34
- findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options: WithoutProjection<mongodb.FindOneAndUpdateOption<TSchema> & { returnOriginal: false, upsert: true }>): Promise<TSchema>
35
- findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: WithoutProjection<mongodb.FindOneAndUpdateOption<TSchema>>): Promise<TSchema | null>
56
+ findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options: WithoutProjection<FindOneAndUpdateOption<TSchema> & { returnOriginal: false, upsert: true }>): Promise<TSchema>
57
+ findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: WithoutProjection<FindOneAndUpdateOption<TSchema>>): Promise<TSchema | null>
36
58
 
37
- 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>>
38
- 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>
59
+ 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>>
60
+ 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>
39
61
 
40
- 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>>
41
- 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>
62
+ 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>>
63
+ 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>
42
64
 
43
- findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options: mongodb.FindOneAndUpdateOption<TSchema> & { returnOriginal: false, upsert: true }): Promise<object>
44
- findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: mongodb.FindOneAndUpdateOption<TSchema>): Promise<object | null>
65
+ findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options: FindOneAndUpdateOption<TSchema> & { returnOriginal: false, upsert: true }): Promise<object>
66
+ findOneAndUpdate (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: FindOneAndUpdateOption<TSchema>): Promise<object | null>
45
67
 
46
- updateOne (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: mongodb.UpdateOneOptions): Promise<{ matched: 0 | 1, modified: 0 | 1 }>
47
- updateMany (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: mongodb.UpdateManyOptions): Promise<{ matched: number, modified: number }>
68
+ updateOne (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: UpdateOneOptions): Promise<{ matched: 0 | 1, modified: 0 | 1 }>
69
+ updateMany (filter: mongodb.FilterQuery<TSchema>, update: mongodb.UpdateQuery<TSchema> | Partial<TSchema>, options?: UpdateManyOptions): Promise<{ matched: number, modified: number }>
48
70
 
49
- deleteOne (filter: mongodb.FilterQuery<TSchema>, options?: mongodb.CommonOptions & { bypassDocumentValidation?: boolean }): Promise<0 | 1>
50
- deleteMany (filter: mongodb.FilterQuery<TSchema>, options?: mongodb.CommonOptions): Promise<number>
71
+ deleteOne (filter: mongodb.FilterQuery<TSchema>, options?: mongodb.CommonOptions & { bypassDocumentValidation?: boolean, hint?: string | object }): Promise<0 | 1>
72
+ deleteMany (filter: mongodb.FilterQuery<TSchema>, options?: mongodb.CommonOptions & { hint?: string | object }): Promise<number>
51
73
 
52
74
  aggregate (pipeline: object[], options?: mongodb.CollectionAggregationOptions): Promise<object[]>
75
+
76
+ createIndex (fieldOrSpec: string | any, options?: mongodb.IndexOptions): Promise<string>
53
77
  }
54
78
 
55
79
  interface FileInfo {
@@ -76,6 +100,7 @@ declare namespace albatross {
76
100
  collection<TSchema extends { _id: any }> (name: string): Collection<TSchema>
77
101
  grid (name?: string): Grid
78
102
  ping (timeout?: number): Promise<void>
103
+ transaction<T> (fn: (session: mongodb.ClientSession) => PromiseLike<T>): Promise<T>
79
104
  close (force?: boolean): Promise<void>
80
105
  }
81
106
 
package/lib/albatross.js CHANGED
@@ -99,6 +99,23 @@ class Albatross {
99
99
  }
100
100
  }
101
101
 
102
+ async transaction (fn) {
103
+ const client = await this[kConnect]()
104
+ const session = client.startSession()
105
+
106
+ let result
107
+
108
+ try {
109
+ await session.withTransaction(async (...args) => {
110
+ result = await fn(...args)
111
+ })
112
+ } finally {
113
+ session.endSession()
114
+ }
115
+
116
+ return result
117
+ }
118
+
102
119
  async close (force) {
103
120
  if (this[kClient] == null) return
104
121
 
package/lib/collection.js CHANGED
@@ -76,12 +76,16 @@ class Collection {
76
76
  }
77
77
  }
78
78
 
79
- async exists (query) {
79
+ async exists (query, opts) {
80
80
  const db = await this.parent.db()
81
81
 
82
82
  // https://blog.serverdensity.com/checking-if-a-document-exists-mongodb-slow-findone-vs-find/
83
83
  const cursor = db.collection(this.name).find(query, { projection: { _id: 1 }, limit: 1 })
84
84
 
85
+ if (opts && opts.hint) {
86
+ cursor.hint(opts.hint)
87
+ }
88
+
85
89
  try {
86
90
  this[kDebug]('exists(%o)', query)
87
91
  const res = await cursor.hasNext()
@@ -199,6 +203,20 @@ class Collection {
199
203
  throw err
200
204
  }
201
205
  }
206
+
207
+ async createIndex (fieldOrSpec, opts) {
208
+ const db = await this.parent.db()
209
+
210
+ try {
211
+ this[kDebug]('createIndex(%o, %o)', fieldOrSpec, opts)
212
+ const res = await db.collection(this.name).createIndex(fieldOrSpec, opts)
213
+ this[kDebug]('reply OK')
214
+ return res
215
+ } catch (err) {
216
+ this[kDebug]('reply ERR')
217
+ throw err
218
+ }
219
+ }
202
220
  }
203
221
 
204
222
  module.exports = Collection
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "albatross",
3
- "version": "3.4.1",
3
+ "version": "3.6.0",
4
4
  "license": "MIT",
5
5
  "author": "Linus Unnebäck <linus@folkdatorn.se>",
6
6
  "repository": "LinusU/node-albatross",
package/readme.md CHANGED
@@ -95,6 +95,26 @@ Send the `ping` command to the server, to check that the connection is still int
95
95
 
96
96
  Optionally accepts a timeout in milliseconds.
97
97
 
98
+ #### `.transaction(fn): Promise`
99
+
100
+ 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.
101
+
102
+ Example:
103
+
104
+ ```js
105
+ const user = db.collection('user')
106
+
107
+ const result = await db.transaction(async (session) => {
108
+ await user.insert({ name: 'Linus', born: 1992 }, { session })
109
+ await user.insert({ name: 'Steve', born: 1955 }, { session })
110
+
111
+ return await user.findOne({ born: 1992 }, { session })
112
+ })
113
+
114
+ console.log('Hello ' + result.name)
115
+ //=> Hello Linus
116
+ ```
117
+
98
118
  #### `.close(): Promise<void>`
99
119
 
100
120
  Closes the connection to the server.