docs(mongo-query-builder): fix pipeline builder examples to match the real API

[nurul3101]

Linked issue

n/a — small change (doc corrections only). The same docs-validation pass also surfaced three product bugs, filed separately: #925, #926, #927.

Summary

Three examples in docs/reference/Mongo Pipeline Builder.md do not match the real query-builder API, so copying them fails at compile or run time. This PR corrects them: group() callbacks receive only the field accessor (acc is a module import, and the doc's own later sections already say so), updater callbacks must return an array of update operations (UpdaterResult is ReadonlyArray<…>; the bare-op form throws Unreachable: items.length > 0 but first is undefined), and findOneAndUpdate takes returnDocument: 'before' | 'after' (default 'after') — returnNewDocument is not a recognized option.

All corrections are verified against the source (packages/2-mongo-family/5-query-builders/query-builder/src/builder.ts, update-ops.ts, exports/index.ts) and empirically via executable doc-snippet specs run against mongodb-memory-server.

Testing performed

• Docs-only change; no code paths affected.
• Verified each corrected snippet against the current signatures: group(fn: (fields) => Spec) (builder.ts), UpdaterResult = ReadonlyArray<TypedUpdateOp> | ReadonlyArray<MongoUpdatePipelineStage> (update-ops.ts:189), findOneAndUpdate(updaterFn, { upsert?, returnDocument? }) with returnDocument ?? 'after' (builder.ts:759-774).
• The corrected forms were exercised end-to-end in a local harness of executable doc-reference specs (mongodb-memory-server).

Skill update

n/a — the affected examples live only in docs/reference/Mongo Pipeline Builder.md; no skill under packages/0-shared/skills/ documents these call shapes (checked for returnNewDocument, (f, acc), and the write-method examples).

Checklist

• All commits are signed off (git commit -s) per the DCO.
• I read CONTRIBUTING.md and the change is scoped to one logical concern.
• Tests are updated (n/a — doc-only, no behavioural delta).
• PR title: no Linear ticket exists for this (external-contribution flow per contrib-pr); conventional-commit form used instead.
• The Skill update section above is filled in.

Notes for the reviewer

The doc's prose around find-and-modify was also adjusted to explain the returnDocument default, and a one-line note about array-shaped updater returns was added above the write examples, since the bare-op form typechecks in the reader's head but is a compile error in practice. Product bugs found in the same validation pass (ObjectId equality in match(), raw codec-id inference, raw findOneAndUpdate options) are deliberately not touched here — they're tracked in #925/#926/#927.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated the Mongo pipeline builder reference to match the latest update-operation callback shape.
  • Clarified that updater callbacks must return an array of update operations.
  • Revised examples for update, upsert, and find-and-modify flows to use the new array-based form.
  • Updated the options example to use the current document-return setting.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 6f01e8b8-5c3b-4f7b-a1dc-1e07af9cbe8b

📥 Commits

Reviewing files that changed from the base of the PR and between 23a9576 and e4c81d6.

📒 Files selected for processing (1)

• docs/reference/Mongo Pipeline Builder.md

---

📝 Walkthrough

Walkthrough

Documentation for the Mongo pipeline builder was updated to reflect a revised accumulator import/usage pattern in grouping examples and a new requirement that updater callbacks return arrays of update operations, along with an option rename from returnNewDocument to returnDocument.

Changes

Mongo Pipeline Builder Documentation

Layer / File(s)	Summary
Grouping example accumulator syntax docs/reference/Mongo Pipeline Builder.md	The grounding example imports acc alongside mongoQuery, and the group callback no longer takes an accumulator parameter, instead using the imported acc identifier.
Updater callback array return requirement docs/reference/Mongo Pipeline Builder.md	Unqualified writes (updateAll, upsertOne) and filtered writes (updateOne, upsertOne, findOneAndUpdate) now show updater callbacks returning arrays of update operations, and the findOneAndUpdate options example changes returnNewDocument: true to returnDocument: 'after'.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Related PRs: None specified in provided context.

Suggested labels: documentation

Suggested reviewers: None specified in provided context.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: fixing Mongo pipeline builder docs to match the real API.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/mongo-pipeline-builder-corrections

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

size-limit report 📦

Path	Size
postgres / no-emit	148.99 KB (0%)
postgres / emit	126.45 KB (0%)
mongo / no-emit	98.2 KB (0%)
mongo / emit	89.39 KB (0%)
cf-worker / no-emit	175.55 KB (0%)
cf-worker / emit	150.97 KB (0%)

[pkg-pr-new]

Open in StackBlitz

@prisma-next/extension-author-tools

npm i https://pkg.pr.new/@prisma-next/extension-author-tools@928

@prisma-next/mongo-runtime

npm i https://pkg.pr.new/@prisma-next/mongo-runtime@928

@prisma-next/family-mongo

npm i https://pkg.pr.new/@prisma-next/family-mongo@928

@prisma-next/sql-runtime

npm i https://pkg.pr.new/@prisma-next/sql-runtime@928

@prisma-next/family-sql

npm i https://pkg.pr.new/@prisma-next/family-sql@928

@prisma-next/extension-arktype-json

npm i https://pkg.pr.new/@prisma-next/extension-arktype-json@928

@prisma-next/middleware-cache

npm i https://pkg.pr.new/@prisma-next/middleware-cache@928

@prisma-next/mongo

npm i https://pkg.pr.new/@prisma-next/mongo@928

@prisma-next/extension-paradedb

npm i https://pkg.pr.new/@prisma-next/extension-paradedb@928

@prisma-next/extension-pgvector

npm i https://pkg.pr.new/@prisma-next/extension-pgvector@928

@prisma-next/extension-postgis

npm i https://pkg.pr.new/@prisma-next/extension-postgis@928

@prisma-next/postgres

npm i https://pkg.pr.new/@prisma-next/postgres@928

@prisma-next/sql-orm-client

npm i https://pkg.pr.new/@prisma-next/sql-orm-client@928

@prisma-next/sqlite

npm i https://pkg.pr.new/@prisma-next/sqlite@928

@prisma-next/extension-supabase

npm i https://pkg.pr.new/@prisma-next/extension-supabase@928

@prisma-next/target-mongo

npm i https://pkg.pr.new/@prisma-next/target-mongo@928

@prisma-next/adapter-mongo

npm i https://pkg.pr.new/@prisma-next/adapter-mongo@928

@prisma-next/driver-mongo

npm i https://pkg.pr.new/@prisma-next/driver-mongo@928

@prisma-next/contract

npm i https://pkg.pr.new/@prisma-next/contract@928

@prisma-next/utils

npm i https://pkg.pr.new/@prisma-next/utils@928

@prisma-next/config

npm i https://pkg.pr.new/@prisma-next/config@928

@prisma-next/errors

npm i https://pkg.pr.new/@prisma-next/errors@928

@prisma-next/framework-components

npm i https://pkg.pr.new/@prisma-next/framework-components@928

@prisma-next/operations

npm i https://pkg.pr.new/@prisma-next/operations@928

@prisma-next/ts-render

npm i https://pkg.pr.new/@prisma-next/ts-render@928

@prisma-next/contract-authoring

npm i https://pkg.pr.new/@prisma-next/contract-authoring@928

@prisma-next/ids

npm i https://pkg.pr.new/@prisma-next/ids@928

@prisma-next/psl-parser

npm i https://pkg.pr.new/@prisma-next/psl-parser@928

@prisma-next/psl-printer

npm i https://pkg.pr.new/@prisma-next/psl-printer@928

@prisma-next/cli

npm i https://pkg.pr.new/@prisma-next/cli@928

@prisma-next/cli-telemetry

npm i https://pkg.pr.new/@prisma-next/cli-telemetry@928

@prisma-next/config-loader

npm i https://pkg.pr.new/@prisma-next/config-loader@928

@prisma-next/emitter

npm i https://pkg.pr.new/@prisma-next/emitter@928

@prisma-next/language-server

npm i https://pkg.pr.new/@prisma-next/language-server@928

@prisma-next/migration-tools

npm i https://pkg.pr.new/@prisma-next/migration-tools@928

prisma-next

npm i https://pkg.pr.new/prisma-next@928

@prisma-next/vite-plugin-contract-emit

npm i https://pkg.pr.new/@prisma-next/vite-plugin-contract-emit@928

@prisma-next/mongo-codec

npm i https://pkg.pr.new/@prisma-next/mongo-codec@928

@prisma-next/mongo-contract

npm i https://pkg.pr.new/@prisma-next/mongo-contract@928

@prisma-next/mongo-value

npm i https://pkg.pr.new/@prisma-next/mongo-value@928

@prisma-next/mongo-contract-psl

npm i https://pkg.pr.new/@prisma-next/mongo-contract-psl@928

@prisma-next/mongo-contract-ts

npm i https://pkg.pr.new/@prisma-next/mongo-contract-ts@928

@prisma-next/mongo-emitter

npm i https://pkg.pr.new/@prisma-next/mongo-emitter@928

@prisma-next/mongo-schema-ir

npm i https://pkg.pr.new/@prisma-next/mongo-schema-ir@928

@prisma-next/mongo-query-ast

npm i https://pkg.pr.new/@prisma-next/mongo-query-ast@928

@prisma-next/mongo-orm

npm i https://pkg.pr.new/@prisma-next/mongo-orm@928

@prisma-next/mongo-query-builder

npm i https://pkg.pr.new/@prisma-next/mongo-query-builder@928

@prisma-next/mongo-lowering

npm i https://pkg.pr.new/@prisma-next/mongo-lowering@928

@prisma-next/mongo-wire

npm i https://pkg.pr.new/@prisma-next/mongo-wire@928

@prisma-next/sql-contract

npm i https://pkg.pr.new/@prisma-next/sql-contract@928

@prisma-next/sql-errors

npm i https://pkg.pr.new/@prisma-next/sql-errors@928

@prisma-next/sql-operations

npm i https://pkg.pr.new/@prisma-next/sql-operations@928

@prisma-next/sql-schema-ir

npm i https://pkg.pr.new/@prisma-next/sql-schema-ir@928

@prisma-next/sql-contract-psl

npm i https://pkg.pr.new/@prisma-next/sql-contract-psl@928

@prisma-next/sql-contract-ts

npm i https://pkg.pr.new/@prisma-next/sql-contract-ts@928

@prisma-next/sql-contract-emitter

npm i https://pkg.pr.new/@prisma-next/sql-contract-emitter@928

@prisma-next/sql-lane-query-builder

npm i https://pkg.pr.new/@prisma-next/sql-lane-query-builder@928

@prisma-next/sql-relational-core

npm i https://pkg.pr.new/@prisma-next/sql-relational-core@928

@prisma-next/sql-builder

npm i https://pkg.pr.new/@prisma-next/sql-builder@928

@prisma-next/target-postgres

npm i https://pkg.pr.new/@prisma-next/target-postgres@928

@prisma-next/target-sqlite

npm i https://pkg.pr.new/@prisma-next/target-sqlite@928

@prisma-next/adapter-postgres

npm i https://pkg.pr.new/@prisma-next/adapter-postgres@928

@prisma-next/adapter-sqlite

npm i https://pkg.pr.new/@prisma-next/adapter-sqlite@928

@prisma-next/driver-postgres

npm i https://pkg.pr.new/@prisma-next/driver-postgres@928

@prisma-next/driver-sqlite

npm i https://pkg.pr.new/@prisma-next/driver-sqlite@928

commit: e4c81d6