Skip to content

docs: add TypeScript Query guide with info on lean() + transform() #15377

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 29, 2025

Conversation

vkarpov15
Copy link
Collaborator

Fix #15311

Summary

Add some recommendations on how to use lean() and transform() together based on discussion from #15311. Also good to have a "Queries" page for more info on how to use queries in TypeScript.

Examples

@vkarpov15 vkarpov15 added this to the 8.14.1 milestone Apr 28, 2025
Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR updates the documentation by adding a guide for using Mongoose queries in TypeScript, especially focusing on recommendations for ordering the use of lean() and transform().

  • Added a new "Queries in TypeScript" section
  • Provided code examples demonstrating the proper use and common pitfalls of chaining lean() and transform()
  • Clarified the recommendation to call lean() before transform() for proper type inference
Files not reviewed (1)
  • docs/layout.pug: Language not supported

@hasezoey hasezoey added docs This issue is due to a mistake or omission in the mongoosejs.com documentation typescript Types or Types-test related issue / Pull Request labels Apr 29, 2025
@vkarpov15 vkarpov15 merged commit 55eef44 into master Apr 29, 2025
3 checks passed
@vkarpov15 vkarpov15 deleted the vkarpov15/gh-15311 branch April 29, 2025 14:08
KleilsonSantos added a commit to KleilsonSantos/Mongo-RestFull-API that referenced this pull request May 23, 2025
![snyk-top-banner](https://res.cloudinary.com/snyk/image/upload/r-d/scm-platform/snyk-pull-requests/pr-banner-default.svg)


<h3>Snyk has created this PR to upgrade mongoose from 8.12.1 to
8.14.1.</h3>

:information_source: Keep your dependencies up-to-date. This makes it
easier to fix existing vulnerabilities and to more quickly identify and
fix newly disclosed vulnerabilities when they affect your project.

<hr/>


- The recommended version is **7 versions** ahead of your current
version.

- The recommended version was released **22 days ago**.



<details>
<summary><b>Release notes</b></summary>
<br/>
  <details>
    <summary>Package name: <b>mongoose</b></summary>
    <ul>
      <li>
<b>8.14.1</b> - <a
href="https://redirect.github.com/Automattic/mongoose/releases/tag/8.14.1">2025-04-29</a></br><h1>8.14.1
/ 2025-04-29</h1>
<ul>
<li>fix: correct change tracking with maps of arrays of primitives and
maps of maps <a class="issue-link js-issue-link" data-error-text="Failed
to load title" data-id="3020119547" data-permission-text="Title is
private" data-url="Automattic/mongoose#15374"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15374/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15374">#15374</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="2990690538" data-permission-text="Title is private"
data-url="Automattic/mongoose#15350"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15350/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15350">#15350</a></li>
<li>fix(populate): consistently convert Buffer representation of UUID to
hex string to avoid confusing populate assignment <a class="issue-link
js-issue-link" data-error-text="Failed to load title"
data-id="3028671691" data-permission-text="Title is private"
data-url="Automattic/mongoose#15383"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15383/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15383">#15383</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="3028403612" data-permission-text="Title is private"
data-url="Automattic/mongoose#15382"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15382/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15382">#15382</a></li>
<li>docs: add TypeScript Query guide with info on lean() + transform()
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="3025739184" data-permission-text="Title is private"
data-url="Automattic/mongoose#15377"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15377/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15377">#15377</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="2909610525" data-permission-text="Title is private"
data-url="Automattic/mongoose#15311"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15311/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15311">#15311</a></li>
</ul>
      </li>
      <li>
<b>8.14.0</b> - <a
href="https://redirect.github.com/Automattic/mongoose/releases/tag/8.14.0">2025-04-25</a></br><h1>8.14.0
/ 2025-04-25</h1>
<ul>
<li>feat: upgrade MongoDB driver -&gt; 6.16 <a class="issue-link
js-issue-link" data-error-text="Failed to load title"
data-id="3018517569" data-permission-text="Title is private"
data-url="Automattic/mongoose#15371"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15371/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15371">#15371</a></li>
<li>feat: implement Query findById methods <a class="issue-link
js-issue-link" data-error-text="Failed to load title"
data-id="2964535745" data-permission-text="Title is private"
data-url="Automattic/mongoose#15337"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15337/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15337">#15337</a>
<a href="https://redirect.github.com/sderrow">sderrow</a></li>
<li>feat(subdocument): support schematype-level minimize option to
disable minimizing empty subdocuments <a class="issue-link
js-issue-link" data-error-text="Failed to load title"
data-id="2964364490" data-permission-text="Title is private"
data-url="Automattic/mongoose#15336"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15336/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15336">#15336</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="2916407638" data-permission-text="Title is private"
data-url="Automattic/mongoose#15313"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15313/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15313">#15313</a></li>
<li>feat: add skipOriginalStackTraces option to avoid stack trace
performance overhead <a class="issue-link js-issue-link"
data-error-text="Failed to load title" data-id="2973087871"
data-permission-text="Title is private"
data-url="Automattic/mongoose#15345"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15345/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15345">#15345</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="2803911966" data-permission-text="Title is private"
data-url="Automattic/mongoose#15194"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15194/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15194">#15194</a></li>
<li>fix(model): disallow Model.findOneAndUpdate(update) and fix
TypeScript types re: findOneAndUpdate <a class="issue-link
js-issue-link" data-error-text="Failed to load title"
data-id="3009226624" data-permission-text="Title is private"
data-url="Automattic/mongoose#15365"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15365/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15365">#15365</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="3006742365" data-permission-text="Title is private"
data-url="Automattic/mongoose#15363"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15363/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15363">#15363</a></li>
<li>types: correctly recurse in InferRawDocType <a class="issue-link
js-issue-link" data-error-text="Failed to load title"
data-id="2997936879" data-permission-text="Title is private"
data-url="Automattic/mongoose#15357"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15357/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15357">#15357</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="2581233621" data-permission-text="Title is private"
data-url="Automattic/mongoose#14954"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/14954/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/14954">#14954</a>
<a
href="https://redirect.github.com/JavaScriptBach">JavaScriptBach</a></li>
<li>types: include virtuals in toJSON and toObject output if virtuals:
true set <a class="issue-link js-issue-link" data-error-text="Failed to
load title" data-id="2975132650" data-permission-text="Title is private"
data-url="Automattic/mongoose#15346"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15346/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15346">#15346</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="2920983347" data-permission-text="Title is private"
data-url="Automattic/mongoose#15316"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15316/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15316">#15316</a></li>
<li>types: make init hooks types accurately reflect runtime behavior <a
class="issue-link js-issue-link" data-error-text="Failed to load title"
data-id="2953291245" data-permission-text="Title is private"
data-url="Automattic/mongoose#15331"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15331/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15331">#15331</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="2900387338" data-permission-text="Title is private"
data-url="Automattic/mongoose#15301"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15301/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15301">#15301</a></li>
</ul>
      </li>
      <li>
<b>8.13.3</b> - <a
href="https://redirect.github.com/Automattic/mongoose/releases/tag/8.13.3">2025-04-24</a></br><h1>8.13.3
/ 2025-04-24</h1>
<ul>
<li>fix: export MongooseBulkSaveIncompleteError <a class="issue-link
js-issue-link" data-error-text="Failed to load title"
data-id="3018324222" data-permission-text="Title is private"
data-url="Automattic/mongoose#15370"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15370/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15370">#15370</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="3016503732" data-permission-text="Title is private"
data-url="Automattic/mongoose#15369"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15369/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15369">#15369</a></li>
<li>fix: clone POJOs and arrays when casting query filter to avoid
mutating objects <a class="issue-link js-issue-link"
data-error-text="Failed to load title" data-id="3011345200"
data-permission-text="Title is private"
data-url="Automattic/mongoose#15367"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15367/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15367">#15367</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="3008658821" data-permission-text="Title is private"
data-url="Automattic/mongoose#15364"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15364/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15364">#15364</a></li>
<li>types(connection): add Connection.prototype.bulkWrite() to types <a
class="issue-link js-issue-link" data-error-text="Failed to load title"
data-id="3011492862" data-permission-text="Title is private"
data-url="Automattic/mongoose#15368"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15368/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15368">#15368</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="3001950341" data-permission-text="Title is private"
data-url="Automattic/mongoose#15359"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15359/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15359">#15359</a></li>
<li>docs: add version requirements to v7 migration docs <a
class="issue-link js-issue-link" data-error-text="Failed to load title"
data-id="3004536206" data-permission-text="Title is private"
data-url="Automattic/mongoose#15361"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15361/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15361">#15361</a>
<a href="https://redirect.github.com/SethFalco">SethFalco</a></li>
<li>docs: update links in deleteOne &amp; deleteMany API def <a
class="issue-link js-issue-link" data-error-text="Failed to load title"
data-id="3002799852" data-permission-text="Title is private"
data-url="Automattic/mongoose#15360"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15360/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15360">#15360</a>
<a href="https://redirect.github.com/Elliot67">Elliot67</a></li>
<li>docs: adds Model#count to list of fns callback removed from <a
class="issue-link js-issue-link" data-error-text="Failed to load title"
data-id="2984680663" data-permission-text="Title is private"
data-url="Automattic/mongoose#15349"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15349/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15349">#15349</a>
<a href="https://redirect.github.com/SethFalco">SethFalco</a></li>
</ul>
      </li>
      <li>
<b>8.13.2</b> - <a
href="https://redirect.github.com/Automattic/mongoose/releases/tag/8.13.2">2025-04-03</a></br><h1>8.13.2
/ 2025-04-03</h1>
<ul>
<li>fix: avoid double calling validators on paths in document arrays
underneath subdocuments <a class="issue-link js-issue-link"
data-error-text="Failed to load title" data-id="2964589348"
data-permission-text="Title is private"
data-url="Automattic/mongoose#15338"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15338/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15338">#15338</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="2962842706" data-permission-text="Title is private"
data-url="Automattic/mongoose#15335"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15335/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15335">#15335</a></li>
</ul>
      </li>
      <li>
<b>8.13.1</b> - <a
href="https://redirect.github.com/Automattic/mongoose/releases/tag/8.13.1">2025-03-28</a></br><h1>8.13.1
/ 2025-03-28</h1>
<ul>
<li>fix(populate): handle virtual populate on array of UUIDs <a
class="issue-link js-issue-link" data-error-text="Failed to load title"
data-id="2950829127" data-permission-text="Title is private"
data-url="Automattic/mongoose#15329"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15329/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15329">#15329</a>
<a class="issue-link js-issue-link" data-error-text="Failed to load
title" data-id="2920867131" data-permission-text="Title is private"
data-url="Automattic/mongoose#15315"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15315/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15315">#15315</a></li>
<li>types: allow default function returning undefined with DocType
override <a class="issue-link js-issue-link" data-error-text="Failed to
load title" data-id="2947550615" data-permission-text="Title is private"
data-url="Automattic/mongoose#15328"
data-hovercard-type="pull_request"
data-hovercard-url="/Automattic/mongoose/pull/15328/hovercard"
href="https://redirect.github.com/Automattic/mongoose/pull/15328">#15328</a></li>
</ul>
      </li>
      <li>
<b>8.13.0</b> - <a
href="https://redirect.github.com/Automattic/mongoose/releases/tag/8.13.0">2025-03-24</a></br><h1>8.13.0
/ 2025-03-24</h1>
<ul>
<li>feat: bump mongodb driver -&gt; 6.15.0</li>
<li>feat: support custom types exported from driver <a class="issue-link
js-issue-link" data-error-text="Failed to load title"
data-id="2932613125" data-permission-text="Title is private"
data-url="Automattic/mongoose#15321"
data-hovercard-type="issue"
data-hovercard-url="/Automattic/mongoose/issues/15321/hovercard"
href="https://redirect.github.com/Automattic/mongoose/issues/15321">#15321</a></li>
</ul>
      </li>
      <li>
        <b>8.12.2</b> - 2025-03-21
      </li>
      <li>
        <b>8.12.1</b> - 2025-03-04
      </li>
    </ul>
from <a
href="https://redirect.github.com/Automattic/mongoose/releases">mongoose
GitHub release notes</a>
  </details>
</details>

---

> [!IMPORTANT]
>
> - Check the changes in this PR to ensure they won't cause issues with
your project.
> - This PR was automatically created by Snyk using the credentials of a
real user.

---

**Note:** _You are seeing this because you or someone else with access
to this repository has authorized Snyk to open upgrade PRs._

**For more information:** <img
src="https://api.segment.io/v1/pixel/track?data=eyJ3cml0ZUtleSI6InJyWmxZcEdHY2RyTHZsb0lYd0dUcVg4WkFRTnNCOUEwIiwiYW5vbnltb3VzSWQiOiIyMjEyNTFhNy1lOGJhLTQyZjYtOGU0My01MzllOGU3NjRhYTciLCJldmVudCI6IlBSIHZpZXdlZCIsInByb3BlcnRpZXMiOnsicHJJZCI6IjIyMTI1MWE3LWU4YmEtNDJmNi04ZTQzLTUzOWU4ZTc2NGFhNyJ9fQ=="
width="0" height="0"/>

> - 🧐 [View latest project
report](https://app.snyk.io/org/kdsdesign1/project/6dfd2c96-abbb-46a3-be3c-7747489f415d?utm_source&#x3D;github&amp;utm_medium&#x3D;referral&amp;page&#x3D;upgrade-pr)
> - 📜 [Customise PR
templates](https://docs.snyk.io/scan-using-snyk/pull-requests/snyk-fix-pull-or-merge-requests/customize-pr-templates?utm_source=&utm_content=fix-pr-template)
> - 🛠 [Adjust upgrade PR
settings](https://app.snyk.io/org/kdsdesign1/project/6dfd2c96-abbb-46a3-be3c-7747489f415d/settings/integration?utm_source&#x3D;github&amp;utm_medium&#x3D;referral&amp;page&#x3D;upgrade-pr)
> - 🔕 [Ignore this dependency or unsubscribe from future upgrade
PRs](https://app.snyk.io/org/kdsdesign1/project/6dfd2c96-abbb-46a3-be3c-7747489f415d/settings/integration?pkg&#x3D;mongoose&amp;utm_source&#x3D;github&amp;utm_medium&#x3D;referral&amp;page&#x3D;upgrade-pr#auto-dep-upgrades)

[//]: #
'snyk:metadata:{"customTemplate":{"variablesUsed":[],"fieldsUsed":[]},"dependencies":[{"name":"mongoose","from":"8.12.1","to":"8.14.1"}],"env":"prod","hasFixes":false,"isBreakingChange":false,"isMajorUpgrade":false,"issuesToFix":[],"prId":"221251a7-e8ba-42f6-8e43-539e8e764aa7","prPublicId":"221251a7-e8ba-42f6-8e43-539e8e764aa7","packageManager":"npm","priorityScoreList":[],"projectPublicId":"6dfd2c96-abbb-46a3-be3c-7747489f415d","projectUrl":"https://app.snyk.io/org/kdsdesign1/project/6dfd2c96-abbb-46a3-be3c-7747489f415d?utm_source=github&utm_medium=referral&page=upgrade-pr","prType":"upgrade","templateFieldSources":{"branchName":"default","commitMessage":"default","description":"default","title":"default"},"templateVariants":[],"type":"auto","upgrade":[],"upgradeInfo":{"versionsDiff":7,"publishedDate":"2025-04-29T21:44:37.328Z"},"vulns":[]}'
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs This issue is due to a mistake or omission in the mongoosejs.com documentation typescript Types or Types-test related issue / Pull Request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

How to type QueryWithHelpers so that it returns both HydratedDocument and FlattenMaps?
2 participants