Skip to content

Commit 8bb25aa

Browse files
drenthernitish-mehta
drenther
authored and
nitish-mehta
committed
Tests added, dependencies and docs updated (#3)
* Tests added * deps updated for correct @types handling * README and docs updated
1 parent 954a2da commit 8bb25aa

File tree

7 files changed

+2491
-56
lines changed

7 files changed

+2491
-56
lines changed

‎README.md

+104-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,105 @@
11
# mongoose-transact-utils
2-
Helper methods for Mongoose and MongoDB transactions
2+
3+
Helper methods for Mongoose and MongoDB transactions. The library comes with @types for Typescript users.
4+
5+
## Installation
6+
7+
```shell
8+
npm i mongoose-transact-utils
9+
```
10+
11+
OR
12+
13+
```shell
14+
yarn add mongoose-transact-utils
15+
```
16+
17+
## API Reference and Examples
18+
19+
### A simple use case for transaction
20+
21+
```js
22+
const { runInTransaction } = require('mongoose-transact-utils');
23+
24+
const { User } = require('./models');
25+
26+
// any queries or write you want to do using transaction
27+
(async () => {
28+
// runInTransction catches any error in the callback to abort the transaction session
29+
// and then rethrows the error for you to handle the reporting
30+
await runInTransaction(async session => {
31+
// run any queries here
32+
await addFriend('John', 'Jane', session);
33+
});
34+
35+
console.log('John and Jane are friend now!');
36+
})();
37+
38+
async function addFriend(nameA, nameB, session) {
39+
const userA = await User.find({ name: nameA }).session(session);
40+
const userB = await User.find({ name: nameB }).session(session);
41+
42+
userA.friends.push(userB._id);
43+
userB.friends.push(userA._id);
44+
45+
await userA.save();
46+
await userB.save();
47+
}
48+
```
49+
50+
### Usage with several different mongoose APIs
51+
52+
```js
53+
const { runInTransaction } = require('mongoose-transact-utils');
54+
const { User } = require('./models');
55+
56+
async function example() {
57+
await runInTransaction(async session => {
58+
// all the query methods listed here - https://mongoosejs.com/docs/queries.html
59+
// session works with query methods as follows -
60+
const user = await User.findOne({}).session(session);
61+
62+
// as mentioned earlier, if you use save
63+
// it will use the associated session ($session)
64+
await users.save();
65+
66+
// apart from using $session to set another session
67+
// you can also pass it as an option
68+
await users.save({ session });
69+
70+
// you can also use the options object for passing session
71+
await User.find({}, null, { session });
72+
73+
// works with where as well
74+
await User.where({}).session(session);
75+
76+
// anywhere where queryOptions object can be passed, it accepts the session
77+
// for example
78+
await User.create(
79+
[
80+
/* some date */
81+
],
82+
{ session }
83+
);
84+
await User.bulkWrite(
85+
[
86+
/* some update commands */
87+
],
88+
{ session }
89+
);
90+
91+
// session can be used with aggregation as well
92+
await User.aggregate([
93+
/* pipeline */
94+
]).session(session);
95+
96+
// here is an example with populate, skip, limit, etc.
97+
// you can chain session like all other similiar methods
98+
await User.find({})
99+
.skip(10)
100+
.limit(10)
101+
.populate('address')
102+
.session(session);
103+
});
104+
}
105+
```

‎docs/globals.html

+88-3
Original file line numberDiff line numberDiff line change
@@ -921,7 +921,92 @@
921921
<div class="content-wrap">
922922
<div class="tsd-panel tsd-typography">
923923
<h1 id="mongoose-transact-utils">mongoose-transact-utils</h1>
924-
<p>Helper methods for Mongoose and MongoDB transactions</p>
924+
<p>Helper methods for Mongoose and MongoDB transactions. The library comes with @types for Typescript users.</p>
925+
<h2 id="installation">Installation</h2>
926+
<pre><code class="language-shell">npm i mongoose-transact-utils</code></pre>
927+
<p>OR</p>
928+
<pre><code class="language-shell">yarn add mongoose-transact-utils</code></pre>
929+
<h2 id="api-reference-and-examples">API Reference and Examples</h2>
930+
<h3 id="a-simple-use-case-for-transaction">A simple use case for transaction</h3>
931+
<pre><code class="language-js"><span class="hljs-keyword">const</span> { runInTransaction } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'mongoose-transact-utils'</span>);
932+
933+
<span class="hljs-keyword">const</span> { User } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'./models'</span>);
934+
935+
<span class="hljs-comment">// any queries or write you want to do using transaction</span>
936+
(<span class="hljs-keyword">async</span> () =&gt; {
937+
<span class="hljs-comment">// runInTransction catches any error in the callback to abort the transaction session</span>
938+
<span class="hljs-comment">// and then rethrows the error for you to handle the reporting</span>
939+
<span class="hljs-keyword">await</span> runInTransaction(<span class="hljs-keyword">async</span> session =&gt; {
940+
<span class="hljs-comment">// run any queries here</span>
941+
<span class="hljs-keyword">await</span> addFriend(<span class="hljs-string">'John'</span>, <span class="hljs-string">'Jane'</span>, session);
942+
});
943+
944+
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'John and Jane are friend now!'</span>);
945+
})();
946+
947+
<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">addFriend</span>(<span class="hljs-params">nameA, nameB, session</span>) </span>{
948+
<span class="hljs-keyword">const</span> userA = <span class="hljs-keyword">await</span> User.find({ <span class="hljs-attr">name</span>: nameA }).session(session);
949+
<span class="hljs-keyword">const</span> userB = <span class="hljs-keyword">await</span> User.find({ <span class="hljs-attr">name</span>: nameB }).session(session);
950+
951+
userA.friends.push(userB._id);
952+
userB.friends.push(userA._id);
953+
954+
<span class="hljs-keyword">await</span> userA.save();
955+
<span class="hljs-keyword">await</span> userB.save();
956+
}</code></pre>
957+
<h3 id="usage-with-several-different-mongoose-apis">Usage with several different mongoose APIs</h3>
958+
<pre><code class="language-js"><span class="hljs-keyword">const</span> { runInTransaction } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'mongoose-transact-utils'</span>);
959+
<span class="hljs-keyword">const</span> { User } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'./models'</span>);
960+
961+
<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">example</span>(<span class="hljs-params"></span>) </span>{
962+
<span class="hljs-keyword">await</span> runInTransaction(<span class="hljs-keyword">async</span> session =&gt; {
963+
<span class="hljs-comment">// all the query methods listed here - https://mongoosejs.com/docs/queries.html</span>
964+
<span class="hljs-comment">// session works with query methods as follows -</span>
965+
<span class="hljs-keyword">const</span> user = <span class="hljs-keyword">await</span> User.findOne({}).session(session);
966+
967+
<span class="hljs-comment">// as mentioned earlier, if you use save</span>
968+
<span class="hljs-comment">// it will use the associated session ($session)</span>
969+
<span class="hljs-keyword">await</span> users.save();
970+
971+
<span class="hljs-comment">// apart from using $session to set another session</span>
972+
<span class="hljs-comment">// you can also pass it as an option</span>
973+
<span class="hljs-keyword">await</span> users.save({ session });
974+
975+
<span class="hljs-comment">// you can also use the options object for passing session</span>
976+
<span class="hljs-keyword">await</span> User.find({}, <span class="hljs-literal">null</span>, { session });
977+
978+
<span class="hljs-comment">// works with where as well</span>
979+
<span class="hljs-keyword">await</span> User.where({}).session(session);
980+
981+
<span class="hljs-comment">// anywhere where queryOptions object can be passed, it accepts the session</span>
982+
<span class="hljs-comment">// for example</span>
983+
<span class="hljs-keyword">await</span> User.create(
984+
[
985+
<span class="hljs-comment">/* some date */</span>
986+
],
987+
{ session }
988+
);
989+
<span class="hljs-keyword">await</span> User.bulkWrite(
990+
[
991+
<span class="hljs-comment">/* some update commands */</span>
992+
],
993+
{ session }
994+
);
995+
996+
<span class="hljs-comment">// session can be used with aggregation as well</span>
997+
<span class="hljs-keyword">await</span> User.aggregate([
998+
<span class="hljs-comment">/* pipeline */</span>
999+
]).session(session);
1000+
1001+
<span class="hljs-comment">// here is an example with populate, skip, limit, etc.</span>
1002+
<span class="hljs-comment">// you can chain session like all other similiar methods</span>
1003+
<span class="hljs-keyword">await</span> User.find({})
1004+
.skip(<span class="hljs-number">10</span>)
1005+
.limit(<span class="hljs-number">10</span>)
1006+
.populate(<span class="hljs-string">'address'</span>)
1007+
.session(session);
1008+
});
1009+
}</code></pre>
9251010
</div>
9261011
<section class="tsd-panel-group tsd-index-group">
9271012
<h2>Index</h2>
@@ -950,7 +1035,7 @@ <h3>Mutation<wbr>Callback</h3>
9501035
<div class="tsd-signature tsd-kind-icon">Mutation<wbr>Callback<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">function</span></div>
9511036
<aside class="tsd-sources">
9521037
<ul>
953-
<li>Defined in <a href="https://github.com/cashpositive/mongoose-transact-utils/blob/9f45a6f/src/index.ts#L3">index.ts:3</a></li>
1038+
<li>Defined in <a href="https://github.com/cashpositive/mongoose-transact-utils/blob/954a2da/src/index.ts#L3">index.ts:3</a></li>
9541039
</ul>
9551040
</aside>
9561041
<div class="tsd-type-declaration">
@@ -988,7 +1073,7 @@ <h3>run<wbr>InTransaction</h3>
9881073
<li class="tsd-description">
9891074
<aside class="tsd-sources">
9901075
<ul>
991-
<li>Defined in <a href="https://github.com/cashpositive/mongoose-transact-utils/blob/9f45a6f/src/index.ts#L11">index.ts:11</a></li>
1076+
<li>Defined in <a href="https://github.com/cashpositive/mongoose-transact-utils/blob/954a2da/src/index.ts#L11">index.ts:11</a></li>
9921077
</ul>
9931078
</aside>
9941079
<div class="tsd-comment tsd-typography">

‎docs/index.html

+88-3
Original file line numberDiff line numberDiff line change
@@ -921,7 +921,92 @@
921921
<div class="content-wrap">
922922
<div class="tsd-panel tsd-typography">
923923
<h1 id="mongoose-transact-utils">mongoose-transact-utils</h1>
924-
<p>Helper methods for Mongoose and MongoDB transactions</p>
924+
<p>Helper methods for Mongoose and MongoDB transactions. The library comes with @types for Typescript users.</p>
925+
<h2 id="installation">Installation</h2>
926+
<pre><code class="language-shell">npm i mongoose-transact-utils</code></pre>
927+
<p>OR</p>
928+
<pre><code class="language-shell">yarn add mongoose-transact-utils</code></pre>
929+
<h2 id="api-reference-and-examples">API Reference and Examples</h2>
930+
<h3 id="a-simple-use-case-for-transaction">A simple use case for transaction</h3>
931+
<pre><code class="language-js"><span class="hljs-keyword">const</span> { runInTransaction } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'mongoose-transact-utils'</span>);
932+
933+
<span class="hljs-keyword">const</span> { User } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'./models'</span>);
934+
935+
<span class="hljs-comment">// any queries or write you want to do using transaction</span>
936+
(<span class="hljs-keyword">async</span> () =&gt; {
937+
<span class="hljs-comment">// runInTransction catches any error in the callback to abort the transaction session</span>
938+
<span class="hljs-comment">// and then rethrows the error for you to handle the reporting</span>
939+
<span class="hljs-keyword">await</span> runInTransaction(<span class="hljs-keyword">async</span> session =&gt; {
940+
<span class="hljs-comment">// run any queries here</span>
941+
<span class="hljs-keyword">await</span> addFriend(<span class="hljs-string">'John'</span>, <span class="hljs-string">'Jane'</span>, session);
942+
});
943+
944+
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'John and Jane are friend now!'</span>);
945+
})();
946+
947+
<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">addFriend</span>(<span class="hljs-params">nameA, nameB, session</span>) </span>{
948+
<span class="hljs-keyword">const</span> userA = <span class="hljs-keyword">await</span> User.find({ <span class="hljs-attr">name</span>: nameA }).session(session);
949+
<span class="hljs-keyword">const</span> userB = <span class="hljs-keyword">await</span> User.find({ <span class="hljs-attr">name</span>: nameB }).session(session);
950+
951+
userA.friends.push(userB._id);
952+
userB.friends.push(userA._id);
953+
954+
<span class="hljs-keyword">await</span> userA.save();
955+
<span class="hljs-keyword">await</span> userB.save();
956+
}</code></pre>
957+
<h3 id="usage-with-several-different-mongoose-apis">Usage with several different mongoose APIs</h3>
958+
<pre><code class="language-js"><span class="hljs-keyword">const</span> { runInTransaction } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'mongoose-transact-utils'</span>);
959+
<span class="hljs-keyword">const</span> { User } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'./models'</span>);
960+
961+
<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">example</span>(<span class="hljs-params"></span>) </span>{
962+
<span class="hljs-keyword">await</span> runInTransaction(<span class="hljs-keyword">async</span> session =&gt; {
963+
<span class="hljs-comment">// all the query methods listed here - https://mongoosejs.com/docs/queries.html</span>
964+
<span class="hljs-comment">// session works with query methods as follows -</span>
965+
<span class="hljs-keyword">const</span> user = <span class="hljs-keyword">await</span> User.findOne({}).session(session);
966+
967+
<span class="hljs-comment">// as mentioned earlier, if you use save</span>
968+
<span class="hljs-comment">// it will use the associated session ($session)</span>
969+
<span class="hljs-keyword">await</span> users.save();
970+
971+
<span class="hljs-comment">// apart from using $session to set another session</span>
972+
<span class="hljs-comment">// you can also pass it as an option</span>
973+
<span class="hljs-keyword">await</span> users.save({ session });
974+
975+
<span class="hljs-comment">// you can also use the options object for passing session</span>
976+
<span class="hljs-keyword">await</span> User.find({}, <span class="hljs-literal">null</span>, { session });
977+
978+
<span class="hljs-comment">// works with where as well</span>
979+
<span class="hljs-keyword">await</span> User.where({}).session(session);
980+
981+
<span class="hljs-comment">// anywhere where queryOptions object can be passed, it accepts the session</span>
982+
<span class="hljs-comment">// for example</span>
983+
<span class="hljs-keyword">await</span> User.create(
984+
[
985+
<span class="hljs-comment">/* some date */</span>
986+
],
987+
{ session }
988+
);
989+
<span class="hljs-keyword">await</span> User.bulkWrite(
990+
[
991+
<span class="hljs-comment">/* some update commands */</span>
992+
],
993+
{ session }
994+
);
995+
996+
<span class="hljs-comment">// session can be used with aggregation as well</span>
997+
<span class="hljs-keyword">await</span> User.aggregate([
998+
<span class="hljs-comment">/* pipeline */</span>
999+
]).session(session);
1000+
1001+
<span class="hljs-comment">// here is an example with populate, skip, limit, etc.</span>
1002+
<span class="hljs-comment">// you can chain session like all other similiar methods</span>
1003+
<span class="hljs-keyword">await</span> User.find({})
1004+
.skip(<span class="hljs-number">10</span>)
1005+
.limit(<span class="hljs-number">10</span>)
1006+
.populate(<span class="hljs-string">'address'</span>)
1007+
.session(session);
1008+
});
1009+
}</code></pre>
9251010
</div>
9261011
<div style="position:relative;"><a name="typedoc-main-index" class="tsd-anchor"></a></div>
9271012
<section class="tsd-panel-group tsd-index-group">
@@ -951,7 +1036,7 @@ <h3>Mutation<wbr>Callback</h3>
9511036
<div class="tsd-signature tsd-kind-icon">Mutation<wbr>Callback<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">function</span></div>
9521037
<aside class="tsd-sources">
9531038
<ul>
954-
<li>Defined in <a href="https://github.com/cashpositive/mongoose-transact-utils/blob/9f45a6f/src/index.ts#L3">index.ts:3</a></li>
1039+
<li>Defined in <a href="https://github.com/cashpositive/mongoose-transact-utils/blob/954a2da/src/index.ts#L3">index.ts:3</a></li>
9551040
</ul>
9561041
</aside>
9571042
<div class="tsd-type-declaration">
@@ -989,7 +1074,7 @@ <h3>run<wbr>InTransaction</h3>
9891074
<li class="tsd-description">
9901075
<aside class="tsd-sources">
9911076
<ul>
992-
<li>Defined in <a href="https://github.com/cashpositive/mongoose-transact-utils/blob/9f45a6f/src/index.ts#L11">index.ts:11</a></li>
1077+
<li>Defined in <a href="https://github.com/cashpositive/mongoose-transact-utils/blob/954a2da/src/index.ts#L11">index.ts:11</a></li>
9931078
</ul>
9941079
</aside>
9951080
<div class="tsd-comment tsd-typography">

‎package.json

+21-4
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@
55
"main": "src/index.ts",
66
"scripts": {
77
"build": "pack build && typedoc --out docs --target es6 --theme minimal --mode file src",
8-
"publish": "pack publish && ts-node tools/gh-pages-publish"
8+
"publish": "pack publish && ts-node tools/gh-pages-publish",
9+
"test": "jest"
910
},
1011
"repository": {
1112
"type": "git",
@@ -39,21 +40,37 @@
3940
]
4041
]
4142
},
43+
"jest": {
44+
"transform": {
45+
".ts": "ts-jest"
46+
},
47+
"testEnvironment": "node",
48+
"moduleFileExtensions": [
49+
"ts",
50+
"js"
51+
]
52+
},
53+
"dependencies": {
54+
"@types/mongoose": "^5.2",
55+
"typescript": "^3.3.3333"
56+
},
4257
"devDependencies": {
4358
"@pika/pack": "^0.3.5",
4459
"@pika/plugin-build-node": "^0.3.14",
4560
"@pika/plugin-build-types": "^0.3.14",
4661
"@pika/plugin-ts-standard-pkg": "^0.3.14",
47-
"@types/mongoose": "^5.2",
62+
"@types/jest": "^24.0.11",
4863
"@types/node": "^11.11.3",
64+
"jest": "^24.5.0",
65+
"jest-config": "^24.5.0",
4966
"mongoose": "^5.2",
5067
"prettier": "^1.16.4",
68+
"ts-jest": "^24.0.0",
5169
"ts-node": "^8.0.3",
5270
"tslint": "^5.14.0",
5371
"tslint-config-prettier": "^1.18.0",
5472
"tslint-config-standard": "^8.0.1",
55-
"typedoc": "^0.14.2",
56-
"typescript": "^3.3.3333"
73+
"typedoc": "^0.14.2"
5774
},
5875
"peerDependencies": {
5976
"mongoose": "^5.2"

0 commit comments

Comments
 (0)