fix: explicitly document behavior when cursor entity no longer exists

[wschurman]

Why

The one downside of using id-based cursor pagination and subqueries (added in #422, #431) is that it risks the row referenced by the cursor being deleted between pagination requests. It's an edge case though to be clear. Encoding the full cursor alleviates this, but has it's own downsides since trigram similarity isn't encodable and neither are things like Date objects. It is still preferable to use ID-based cursors for all pagination.

But it becomes the library's responsibility to explicitly document what the behavior is when a row referenced by the cursor is no longer present. This PR does this.

How

When the cursor row is no longer present, the tuple evaluates to NULL, which produces a empty page.

The alternative to this behavior is to run an id check query ahead of the pagination query, and throw an error if it doesn't exist, or even return the first page of data if it doesn't exist. Both of these are less optimal since they cause unexpected behavior during results consumption.

So we keep the behavior as is and explicitly document it.

Test Plan

Run new tests.

[wschurman]

• fix: explicitly document behavior when cursor entity no longer exists #453 👈 (View in Graphite)
• fix: eliminate some unnecessary any casts #448
• fix!: change adaptor -> adapter for consistency #452
• chore: docblock improvements #451
• fix: Reorganize constructionUtils to make non-public #454
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (cc78029) to head (00ac642).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##              main      #453    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files          109       109            
  Lines        16000     16013    +13     
  Branches       861      1432   +571     
==========================================
+ Hits         16000     16013    +13     

Flag	Coverage Δ
integration	23.40% <100.00%> (+0.06%)	⬆️
unittest	95.11% <64.28%> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[wschurman]

Merge activity

• Feb 17, 10:40 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Feb 17, 10:53 PM UTC: Graphite rebased this pull request as part of a merge.
• Feb 17, 10:56 PM UTC: @wschurman merged this pull request with Graphite.