Skip to content

feat: add whereBelongsTo relationship constraints - #311

Open
elpete wants to merge 2 commits into
nextfrom
feat/155-where-belongs-to
Open

feat: add whereBelongsTo relationship constraints#311
elpete wants to merge 2 commits into
nextfrom
feat/155-where-belongs-to

Conversation

@elpete

@elpete elpete commented Aug 22, 2026

Copy link
Copy Markdown
Collaborator

Closes #155

Issue review

Recommendation: 9/10. whereBelongsTo is a strong fit for Quick. It expresses a common foreign-key filter in relationship terms, avoids duplicating key and column knowledge at call sites, and follows an established ORM convention.

Reasons for:

  • Callers can pass a loaded parent entity instead of manually extracting its key and remembering the child foreign key.
  • The relationship definition remains the source of truth for aliases, custom keys, and composite keys.
  • Supporting arrays makes the API useful for bulk parent selections without manual tuple construction.
  • The method composes naturally with existing Quick query methods and has an orWhereBelongsTo counterpart.

Reasons against / tradeoffs:

  • Optional relationship-name inference only works for conventional names based on the related entity name; aliases such as author must be explicit.
  • Accepting entities and collections adds validation and grouping logic beyond a simple single-key shortcut.
  • An empty related collection is treated as invalid input rather than silently returning no rows, making accidental empty filters visible.

Test-first result

Five public integration tests were written before implementation for:

  • an explicitly named aliased relationship;
  • conventional relationship-name inference;
  • multiple related entities;
  • composite keys;
  • OR composition.

Before implementation, the focused bundle had 37 passes and 4 errors because whereBelongsTo was missing. The OR case was added after the core method and validates its companion API.

Implementation

  • Add whereBelongsTo( related, relationshipName?, combinator = "and" ) to QuickQB.
  • Accept one Quick entity, an array, or a collection exposing get().
  • Resolve and validate the belongs-to relationship without applying instance constraints.
  • Build grouped OR tuples from the relationship foreign/local key pairs.
  • Add orWhereBelongsTo() as the fluent OR counterpart.
  • Reject empty inputs, mixed entity mappings, and non-belongs-to relationships with focused Quick exceptions.

Validation

  • Focused QueryingRelationshipsSpec: 42 passed, 0 failed, 0 errors
  • Full suite: 500 passed, 0 failed, 0 errors, 3 skipped
  • box run-script format
  • git diff --check

Dependency: latest prerelease qb 14.0.0-beta.3.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant