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

Closes #69

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

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: 4

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

🧪 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

[Makisuo]

Merge-readiness check: this branch already contains current main (b57faf1), so no merge or code changes were needed. The changeset is present. The helpers only post-process run, so they behave the same on the ClickHouse, Postgres, SQLite and D1 dialects.

CI run 40664791388 failed only on known fuzz flakes on main, which are fixed separately in #131:

• compiled row codec retains generated values (d1)
• generated fixtures: query results agree (postgres), a Postgres division by zero
• generated fixtures: union results agree (clickhouse-join-nulls), a ClickHouse ILLEGAL_DIVISION

None of these involve this change. The failed jobs have been re-run.

Verified locally on 0315f9e: bun run build and bun run typecheck are clean, including the new test-d assertions. bun run test against live ClickHouse 26.8 with PGlite and node:sqlite, including fuzz at FUZZ_SCALE=0.3, passed 73 files and 1435 tests. The doc citation, export catalog and doc example checks also pass.

[maple-review-bot]

Maple review

🟢 Confidence 10/10 · safe to merge. Purely additive post-processing over run, with every row-count branch and the no-LIMIT claim pinned on PGlite and in the type tests.
_{no findings · tests covered · risk medium · 1/1 new units observable}

Adds runOne, runOption and runNonEmpty to /database, checking the row count of run and failing with a typed ResultCardinalityError that carries the rule and the actual count. Purely additive and safe to merge.

• runOne returns the single row or fails on zero or many
• runOption returns Option and fails only on more than one row
• runNonEmpty returns a NonEmptyReadonlyArray or fails on zero rows
• ResultCardinalityError is a new tagged error exported from /database

_{0315f9e · What was checked, coverage and telemetry details are on the Maple / review check. Reply "won't fix" to dismiss a finding, or mention @maple-review-bot to ask about one.}