[artile]

Summary by CodeRabbit

• New Features
  • Added database helpers for queries that must return exactly one row, at most one row, or at least one row.
  • The helpers return a row, an optional row, or a non-empty collection, respectively. Cardinality mismatches return a typed error with the expected rule and actual row count; queries are not modified to add a row limit.
• Documentation
  • Added guidance on the helpers and their row-count behavior, and updated database references and troubleshooting advice.

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 7782d047-472c-4cdd-ae0c-cf4374693ff1

Commits

Reviewing files that changed from the base of the PR and between f602dad and 0315f9e.

Files selected for processing: 5

• docs/database.md
• docs/reference.md
• src/database.ts
• src/database/database.test-d.ts
• src/database/database.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

The database API adds runOne, runOption, and runNonEmpty. Each helper checks returned row counts and reports mismatches with ResultCardinalityError. The changes also add public exports, type and runtime tests, and documentation.

Changes: Database cardinality helpers

Layer / File(s)	Summary
Cardinality error and query helpers src/database/errors.ts, src/database/database.ts	Adds ResultCardinalityError with the expected cardinality and actual row count. Adds helpers that return a single row, an optional row, or a non-empty row array according to their cardinality rules.
Public exports and helper validation src/database.ts, src/database/database.test-d.ts, src/database/database.test.ts, docs/database.md, docs/reference.md, docs/troubleshooting.md, .changeset/cardinality-helpers.md	Re-exports the helpers and error. Tests check result types, cardinality outcomes, and that runOne does not add a LIMIT. Documentation describes the helpers and their error behavior.

Priority: Normal

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

Change: Feature

Possibly related PRs

• MapleTechLabs/effect-orm#8: Adds the Database.run API that the cardinality helpers call.
• MapleTechLabs/effect-orm#27: Changes the Runnable contract used by the new helpers.
• MapleTechLabs/effect-orm#19: Changes the accepted insert types in Database.Runnable, which the helpers use.

Suggested reviewers: makisuo

Merge Risk: Minimal · up to 0315f

The new helpers add row-count validation. No merge-blocking issue was identified.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely identifies the three new database cardinality helpers. It matches the main change in the pull request.
Docstring Coverage		Docstring coverage is inconclusive: files from earlier reviews still need to be rechecked within the check's analysis limits. Not blocking.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Finishing Touches: 💡 1

🧪 Generate unit tests (beta)

• Create a new PR

🛠️ Fix failing CI checks: 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}