refactor!: rename count-only ORM terminals

[tensordreams]

Linked issue

n/a — small change

At a glance

const count = await orm.users
  .where(MongoFieldFilter.eq('bio', null))
  .updateAndCount({ bio: 'filled' });

expect(count).toBe(2);

This is the committed Mongo CRUD lifecycle example; before this branch, the same call used .updateCount(...) and returned the same result.

Decision

This PR ships a hard, breaking rename of the count-only ORM mutation terminals across Mongo and SQL: createCount becomes createAndCount, updateCount becomes updateAndCount, and deleteCount becomes deleteAndCount. There are no compatibility aliases; parameter and return signatures, guards, execution behavior, and count semantics remain otherwise unchanged.

Notes for the reviewer

• The old names are removed, not deprecated. Every current in-repo consumer and active reference migrates in the same commit, so the expected downstream action is a direct source rename.
• The Mongo collection diff is larger than the public API change because touching that file triggered the no-bare-casts convert-on-contact rule. The final command-draining path removes caller-selected result generics, treats driver results as unknown, and uses narrow command-specific blindCast reasons; this is a required type-safety cleanup, not a separate product feature or runtime behavior change.
• Broad concurrent pnpm test:packages, pnpm test:integration, pnpm test:e2e, and full Supabase package attempts hit PostgreSQL ECONNRESET, connection termination, and resource-contention timeouts. Every changed test file passed sequentially in isolation, and no rename-related failure was observed; the broad suites are not claimed as passing.
• A tracked-tree audit leaves only CHANGELOG.md:74 and docs/releases/v0.16.0.md:66 on the old names. Those references are intentional history for the API shipped in v0.16.0.

How it fits together

1. The exported Mongo collection interface and SQL collection terminals adopt the three AndCount names.
2. Internal method labels follow the rename through SQL include refinement, annotation metadata, mutation errors, and Mongo guards, while the existing insert/update/delete plans continue to return Promise<number>.
3. Current examples and consumers move with the API, including SQLite e2e coverage, Supabase RLS integration coverage, the error reference, SQL and Mongo scorecards, and active project notes.
4. User-facing guidance is updated in the Mongo query skill and Supabase skill, so generated and maintained examples use the new surface immediately.

Behavior changes & evidence

• Insert-many callers use createAndCount(...). Mongo and SQL still insert the supplied records and return the inserted count. Implemented in the Mongo terminal and SQL terminal; evidenced by the Mongo lifecycle test and SQL integration test.
• Filtered update callers use updateAndCount(...). Filter requirements, update/default/annotation behavior, and backend count semantics are unchanged. Implemented in the Mongo terminal and SQL terminal; evidenced by the Mongo lifecycle test and SQL integration test.
• Filtered delete callers use deleteAndCount(). Filter requirements, deleted records, and backend count semantics are unchanged. Implemented in the Mongo terminal and SQL terminal; evidenced by the Mongo lifecycle test and SQL integration test.
• Compile-time gates move to the new names. updateAndCount and deleteAndCount still require .where(...), and all three terminals retain Promise<number> results and write-annotation typing. See the generated contract type tests and annotation type tests.

Compatibility / migration / risk

• This is a source-breaking API rename: replace createCount with createAndCount, updateCount with updateAndCount, and deleteCount with deleteAndCount in Mongo and SQL ORM consumers.
• No data migration, contract re-emission, query rewrite, or count-semantics change is required.
• No compatibility aliases are provided, consistent with the pre-1.0 CONTRIBUTING guidance.
• The main risk is an external call site or active document missed by the repository audit. All tracked current references were migrated; only the two intentional historical release references remain.

Testing performed

• pnpm install --frozen-lockfile passed and changed no tracked files.
• pnpm build passed with 68 tasks in the earlier run.
• pnpm typecheck passed 143/143 tasks.
• Mongo ORM tests passed: 222 tests.
• SQL ORM client tests passed: 674 tests.
• Mongo demo tests passed: 35 tests.
• Eight affected consumer integration, e2e, and Supabase files passed sequentially: 63 tests total.
• The real Supabase example suite skipped 4 tests because DATABASE_URL and SUPABASE_JWT_SECRET were unavailable.
• pnpm check:upgrade-coverage, pnpm lint:skills, pnpm check:error-reference, affected package builds/typechecks/lints, and git diff --check passed.
• Broad concurrent pnpm test:packages, pnpm test:integration, pnpm test:e2e, and full Supabase package runs hit PostgreSQL ECONNRESET, connection termination, or resource-contention timeouts. Every changed test file passed in isolation and no rename-related failure was observed; these broad suites are not reported as passing.

Skill update

• Updated skills/prisma-next-queries/mongo.md to teach createAndCount, updateAndCount, and deleteAndCount.
• Updated skills/prisma-next-supabase/SKILL.md to use updateAndCount in the RLS write example.
• Added matching 0.16 → 0.17 migration entries to the user upgrade skill and the extension-author upgrade skill.

Alternatives considered

• Keep compatibility aliases for the old names. Rejected because this is an intentional hard rename in a pre-1.0 codebase, and the repository explicitly prefers migrating call sites over backward-compatibility shims.
• Rename only one backend. Rejected because Mongo and SQL expose the same count-only mutation concept; keeping divergent terminal names would make the ORM surfaces harder to learn and document.
• Rewrite historical release references. Rejected because those entries describe the API that actually shipped in v0.16.0; changing them would make the release record inaccurate.

Checklist

• All commits are signed off (git commit -s) per the DCO; the committed branch contains a matching Signed-off-by: trailer.
• I read CONTRIBUTING.md and the change is scoped to one logical concern.
• Tests are updated for the renamed public surface and unchanged count behavior.
• The PR title is in TML-NNNN: <sentence-case title> form — intentionally unchecked because there is no Linear ticket and the operator selected the repository's Conventional Commits convention instead.
• The Skill update section is filled in with both affected skills.

Summary by CodeRabbit

• New Features

  • Renamed count-only ORM mutation methods to createAndCount(), updateAndCount(), and deleteAndCount().
  • Methods continue returning the number of affected rows.

• Documentation

  • Updated ORM, error-reference, feature-support, and role-based query documentation with the new method names.
  • Added upgrade guidance for migrating from the previous method names.

• Tests

  • Updated CRUD, integration, end-to-end, MongoDB, SQL, and row-level security coverage for the renamed APIs.

[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 Plus

Run ID: a387b9d5-df5a-4a57-bf6b-5fc7c2769757

📥 Commits

Reviewing files that changed from the base of the PR and between 645dd32 and b0f4492.

⛔ Files ignored due to path filters (3)

• projects/created-updated-at-authoring/plan.md is excluded by !projects/**
• projects/middleware-intercept-and-cache/api-revision-meta-callback.md is excluded by !projects/**
• projects/middleware-intercept-and-cache/follow-ups.md is excluded by !projects/**

📒 Files selected for processing (28)

• docs/reference/error-reference.md
• examples/mongo-demo/test/crud-lifecycle.test.ts
• examples/supabase/test/real-supabase.acceptance.test.ts
• packages/2-mongo-family/5-query-builders/orm/src/collection.ts
• packages/2-mongo-family/5-query-builders/orm/test/collection.test.ts
• packages/3-extensions/sql-orm-client/src/collection-internal-types.ts
• packages/3-extensions/sql-orm-client/src/collection.ts
• packages/3-extensions/sql-orm-client/src/query-plan-mutations.ts
• packages/3-extensions/sql-orm-client/test/annotations.test.ts
• packages/3-extensions/sql-orm-client/test/annotations.types.test-d.ts
• packages/3-extensions/sql-orm-client/test/collection-variant.test.ts
• packages/3-extensions/sql-orm-client/test/collection.state.test.ts
• packages/3-extensions/sql-orm-client/test/generated-contract-types.test-d.ts
• packages/3-extensions/sql-orm-client/test/orm-namespace-crud.test.ts
• packages/3-extensions/supabase/test/rls-role-binding.integration.test.ts
• scorecard/06-sql-orm-client.md
• scorecard/07-mongodb-query-and-orm.md
• skills/extension-author/prisma-next-extension-upgrade/upgrades/0.16-to-0.17/instructions.md
• skills/prisma-next-queries/mongo.md
• skills/prisma-next-supabase/SKILL.md
• skills/upgrade/prisma-next-upgrade/upgrades/0.16-to-0.17/instructions.md
• test/e2e/framework/test/sqlite/orm.test.ts
• test/integration/test/namespaced-accessors-e2e.integration.test.ts
• test/integration/test/ports/prisma/functional/methods-createMany/methods-createMany.test.ts
• test/integration/test/sql-orm-client/collection-mutation-defaults.test.ts
• test/integration/test/sql-orm-client/create.test.ts
• test/integration/test/sql-orm-client/delete.test.ts
• test/integration/test/sql-orm-client/update.test.ts

🚧 Files skipped from review as they are similar to previous changes (22)

• skills/prisma-next-supabase/SKILL.md
• packages/3-extensions/sql-orm-client/test/collection.state.test.ts
• packages/3-extensions/sql-orm-client/src/query-plan-mutations.ts
• test/integration/test/namespaced-accessors-e2e.integration.test.ts
• packages/3-extensions/sql-orm-client/src/collection-internal-types.ts
• test/integration/test/ports/prisma/functional/methods-createMany/methods-createMany.test.ts
• test/integration/test/sql-orm-client/delete.test.ts
• scorecard/07-mongodb-query-and-orm.md
• docs/reference/error-reference.md
• scorecard/06-sql-orm-client.md
• test/integration/test/sql-orm-client/update.test.ts
• packages/3-extensions/sql-orm-client/test/generated-contract-types.test-d.ts
• packages/3-extensions/sql-orm-client/test/annotations.test.ts
• packages/3-extensions/sql-orm-client/test/orm-namespace-crud.test.ts
• test/integration/test/sql-orm-client/collection-mutation-defaults.test.ts
• examples/mongo-demo/test/crud-lifecycle.test.ts
• packages/3-extensions/supabase/test/rls-role-binding.integration.test.ts
• packages/2-mongo-family/5-query-builders/orm/test/collection.test.ts
• packages/3-extensions/sql-orm-client/test/annotations.types.test-d.ts
• packages/3-extensions/sql-orm-client/src/collection.ts
• test/e2e/framework/test/sqlite/orm.test.ts
• packages/2-mongo-family/5-query-builders/orm/src/collection.ts

---

📝 Walkthrough

Walkthrough

The ORM count-returning mutation methods were renamed from createCount, updateCount, and deleteCount to createAndCount, updateAndCount, and deleteAndCount across SQL and Mongo implementations, types, tests, examples, integrations, documentation, and scorecards. Mongo typing and value-object handling were also refined.

Changes

ORM count terminal rename

Layer / File(s)	Summary
SQL terminal API and error metadata packages/3-extensions/sql-orm-client/src/*	SQL write terminals, refinement literals, and zero-row mutation metadata now use the AndCount names.
Mongo terminal API and result typing packages/2-mongo-family/5-query-builders/orm/src/collection.ts	Mongo collection methods use the renamed terminals; driver results and model metadata use blindCast, and value-object wrapping uses isUnknownRecord.
ORM contract and behavior validation packages/2-mongo-family/5-query-builders/orm/test/*, packages/3-extensions/sql-orm-client/test/*, test/*	Unit, type-level, annotation, state, namespace, variant, integration, and end-to-end coverage uses the renamed methods.
Examples, integrations, and documentation examples/*, docs/*, skills/*, scorecard/*	Examples, acceptance tests, upgrade instructions, documentation, and feature matrices were updated to the new API names.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• prisma/prisma-next#1021: Both changes update ORM.MUTATION_DATA_MISSING construction and metadata around mutation planning.

Suggested reviewers: wmadden-electric

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the breaking rename of count-only ORM terminals across the PR.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch rename-count-operations

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@prisma-next/extension-author-tools

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

@prisma-next/mongo-runtime

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

@prisma-next/family-mongo

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

@prisma-next/sql-runtime

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

@prisma-next/family-sql

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

@prisma-next/extension-arktype-json

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

@prisma-next/middleware-cache

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

@prisma-next/mongo

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

@prisma-next/extension-paradedb

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

@prisma-next/extension-pgvector

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

@prisma-next/extension-postgis

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

@prisma-next/postgres

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

@prisma-next/sql-orm-client

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

@prisma-next/sqlite

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

@prisma-next/extension-supabase

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

@prisma-next/target-mongo

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

@prisma-next/adapter-mongo

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

@prisma-next/driver-mongo

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

@prisma-next/contract

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

@prisma-next/utils

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

@prisma-next/config

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

@prisma-next/errors

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

@prisma-next/framework-components

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

@prisma-next/operations

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

@prisma-next/ts-render

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

@prisma-next/contract-authoring

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

@prisma-next/ids

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

@prisma-next/psl-parser

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

@prisma-next/psl-printer

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

@prisma-next/cli

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

@prisma-next/cli-telemetry

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

@prisma-next/config-loader

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

@prisma-next/emitter

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

@prisma-next/language-server

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

@prisma-next/migration-tools

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

prisma-next

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

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

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

@prisma-next/mongo-codec

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

@prisma-next/mongo-contract

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

@prisma-next/mongo-value

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

@prisma-next/mongo-contract-psl

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

@prisma-next/mongo-contract-ts

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

@prisma-next/mongo-emitter

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

@prisma-next/mongo-schema-ir

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

@prisma-next/mongo-query-ast

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

@prisma-next/mongo-orm

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

@prisma-next/mongo-query-builder

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

@prisma-next/mongo-lowering

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

@prisma-next/mongo-wire

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

@prisma-next/sql-contract

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

@prisma-next/sql-errors

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

@prisma-next/sql-operations

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

@prisma-next/sql-schema-ir

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

@prisma-next/sql-contract-psl

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

@prisma-next/sql-contract-ts

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

@prisma-next/sql-contract-emitter

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

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

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

@prisma-next/sql-relational-core

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

@prisma-next/sql-builder

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

@prisma-next/target-postgres

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

@prisma-next/target-sqlite

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

@prisma-next/adapter-postgres

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

@prisma-next/adapter-sqlite

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

@prisma-next/driver-postgres

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

@prisma-next/driver-sqlite

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

commit: b0f4492

[github-actions]

size-limit report 📦

Path	Size
postgres / no-emit	164.39 KB (+0.01% 🔺)
postgres / emit	146.39 KB (+0.01% 🔺)
mongo / no-emit	100.26 KB (+0.01% 🔺)
mongo / emit	90 KB (+0.02% 🔺)
cf-worker / no-emit	190.1 KB (0%)
cf-worker / emit	170.06 KB (0%)

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/2-mongo-family/5-query-builders/orm/src/collection.ts (1)

198-212: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Remove redundant variant comments.

The blindCast reason strings already explain both no-op returns, so the added prose is avoidable.

As per coding guidelines, “Don't add comments if avoidable, prefer code that expresses its intent.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/2-mongo-family/5-query-builders/orm/src/collection.ts` around lines
198 - 212, Remove the two explanatory comments immediately preceding the
blindCast calls in the variant refinement logic, while preserving both no-op
return paths and their existing blindCast reason strings.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@test/integration/test/ports/prisma/functional/methods-createMany/methods-createMany.test.ts`:
- Line 15: Rename the test title in the methods-createMany test from “should
create many records” to “creates many records” or an equivalent concise
description without “should”.

---

Nitpick comments:
In `@packages/2-mongo-family/5-query-builders/orm/src/collection.ts`:
- Around line 198-212: Remove the two explanatory comments immediately preceding
the blindCast calls in the variant refinement logic, while preserving both no-op
return paths and their existing blindCast reason strings.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: a54ceee2-2ad5-4d9b-97fe-26dfd54f3238

📥 Commits

Reviewing files that changed from the base of the PR and between 5b93273 and 645dd32.

⛔ Files ignored due to path filters (3)

• projects/created-updated-at-authoring/plan.md is excluded by !projects/**
• projects/middleware-intercept-and-cache/api-revision-meta-callback.md is excluded by !projects/**
• projects/middleware-intercept-and-cache/follow-ups.md is excluded by !projects/**

📒 Files selected for processing (26)

• docs/reference/error-reference.md
• examples/mongo-demo/test/crud-lifecycle.test.ts
• examples/supabase/test/real-supabase.acceptance.test.ts
• packages/2-mongo-family/5-query-builders/orm/src/collection.ts
• packages/2-mongo-family/5-query-builders/orm/test/collection.test.ts
• packages/3-extensions/sql-orm-client/src/collection-internal-types.ts
• packages/3-extensions/sql-orm-client/src/collection.ts
• packages/3-extensions/sql-orm-client/src/query-plan-mutations.ts
• packages/3-extensions/sql-orm-client/test/annotations.test.ts
• packages/3-extensions/sql-orm-client/test/annotations.types.test-d.ts
• packages/3-extensions/sql-orm-client/test/collection-variant.test.ts
• packages/3-extensions/sql-orm-client/test/collection.state.test.ts
• packages/3-extensions/sql-orm-client/test/generated-contract-types.test-d.ts
• packages/3-extensions/sql-orm-client/test/orm-namespace-crud.test.ts
• packages/3-extensions/supabase/test/rls-role-binding.integration.test.ts
• scorecard/06-sql-orm-client.md
• scorecard/07-mongodb-query-and-orm.md
• skills/prisma-next-queries/mongo.md
• skills/prisma-next-supabase/SKILL.md
• test/e2e/framework/test/sqlite/orm.test.ts
• test/integration/test/namespaced-accessors-e2e.integration.test.ts
• test/integration/test/ports/prisma/functional/methods-createMany/methods-createMany.test.ts
• test/integration/test/sql-orm-client/collection-mutation-defaults.test.ts
• test/integration/test/sql-orm-client/create.test.ts
• test/integration/test/sql-orm-client/delete.test.ts
• test/integration/test/sql-orm-client/update.test.ts