[QuantumExplorer]

Basic explanation

A ranked query (the "top n" document query) can be pinned to one tag of a list, for example "the most liked posts tagged dash", by writing ['tags', 'contains', 'dash'] in where. The SDK and the node already answer that query, but the SDK's TypeScript type for a pin only listed == and in, so TypeScript code had to force the pin through with a cast. This lets the type accept contains, keeps containsAny out (a ranked query refuses it), and fixes the docs and an error message that still said every pin must be ==.

Issue being fixed or feature implemented

Since #5370 and #5372, an index can name a typed array and a query reads one element with contains. A ranked or having-range query takes such a pin at runtime: parse_where_clause accepts contains, and assert_ranked_shape / assert_having_shape key it as an equality before the ranked grammar, as the server's ranked and having dispatchers do (key_array_element_clauses). containsAny is refused there, since a ranking over several elements would count a document once per element it holds.

The DocumentsIndexPin TypeScript type was not updated, so callers such as Yappr's tagPin in lib/services/ranked-likes.ts needed as unknown as DocumentsIndexPin.

Before:

// error TS2322: Type '"contains"' is not assignable to type '"==" | "=" | "in" | "In"'.
const page = await sdk.documents.ranked({
  dataContractId: SOCIAL,
  documentTypeName: 'like',
  groupBy: 'postId',
  aggregate: { type: 'count' },
  limit: 10,
  where: [['tags', 'contains', 'dash']],
});

// So callers cast a pin the SDK already answers:
const tagPin = ['tags', 'contains', 'dash'] as unknown as DocumentsIndexPin;

After:

// Type-checks as written; no cast.
const page = await sdk.documents.ranked({
  dataContractId: SOCIAL,
  documentTypeName: 'like',
  groupBy: 'postId',
  aggregate: { type: 'count' },
  limit: 10,
  where: [['tags', 'contains', 'dash']],
});

// Still a type error, as the node refuses it:
// where: [['tags', 'containsAny', ['dash', 'news']]]

What was done?

• packages/wasm-sdk/src/queries/document_ranked.rs
  • DocumentsIndexPin gains [string, 'contains' | 'Contains', unknown] (both spellings, as the parser and DocumentWhereOperator take them). containsAny stays out. The type is shared by DocumentsRankedQuery.where and DocumentsHavingQuery.where, and both surfaces accept the pin.
  • JSDoc on the pin type and on both where fields says what a contains pin names and why containsAny is rejected.
  • The ranked shape error no longer says "where entries must be == pins" (it was also stale for in). It now reads: "where entries pin the covering compound index's leading properties with == (contains on a typed array), or one bounded in."
  • New unit test index_pin_union_takes_contains_but_not_contains_any reads the declared union, next to the existing axis_kind_strings_match_the_typescript_union. It fails if contains is dropped or containsAny is added. This is the guard CI enforces: the mocha runs of the TS specs do not type-check.
• packages/js-evo-sdk/tests/unit/facades/documents.spec.ts: a ranked() case with a contains pin, with the query typed as DocumentsRankedQuery.
• packages/js-evo-sdk/README.md: "Pinning a compound index" shows a contains pin and says containsAny cannot pin; the typed array section points to it.

How Has This Been Tested?

• cargo fmt -p wasm-sdk --check passes, and eslint passes on the touched spec.
• With tsc --strict, the old union rejects where: [['tags', 'contains', 'dash']] with the TS2322 error quoted above.
• The wasm-sdk build (yarn build) and the evo-sdk build were still running when this PR was opened. This section will be updated with the tsc check of the new spec against the generated sdk.d.ts, the run of documents.spec.ts, and cargo test -p wasm-sdk --lib index_pin_union.
• Mocha runs these specs through ts-node without type-checking (a spec with a deliberate tuple type error passes), so the Rust test is the guard CI enforces. The typed spec documents the case and type-checks under tsc.

Breaking Changes

None. The type only widens, and the runtime is unchanged apart from the wording of one error message.

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• I have made corresponding changes to the documentation if needed
• If I added or changed GroveDB structure, I described it in the area's structure.rs, regenerated grovedb-structure.json, and checked the structure viewer link posted on this pull request

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

🤖 Generated with Claude Code

PR Hygiene · 874be58

• Bots — coderabbitai ✓ · thepastaclaw not yet — /skip-bots proceeds without the ones not yet reported
• Self-review — post /self-reviewed
• Reviewer requests paused — your 5 review slots are occupied; this PR is excluded from reviewers' queues. Required approvals still count without a slot.
• Build running
• Approvals
  • js-wasm-sdk (packages/js-evo-sdk/README.md, packages/js-evo-sdk/tests/unit/facades/documents.spec.ts, packages/wasm-sdk/src/queries/document_ranked.rs) — shumkov

When every merge requirement is met, the PR Hygiene check passes. Reviewer limits do not block merging; other required GitHub checks and protections still apply.

Summary by CodeRabbit

• New Features

  • Ranked compound-index queries can now use contains to pin a typed-array property to a specific element.
  • Prefix pins support equality or contains, with at most one branching in condition. Range operators and containsAny are not supported as prefix pins.

• Documentation

  • Clarified how to rank array elements or rank within a pinned array element.

[github-actions]

Waiting for bot review — coderabbitai ✓ · thepastaclaw not yet. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: dashpay/platform/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: ce32f04f-1da5-40a8-a975-ef71c5eca694

📥 Commits

Reviewing files that changed from the base of the PR and between 7f7ed87 and 874be58.

📒 Files selected for processing (3)

• packages/js-evo-sdk/README.md
• packages/js-evo-sdk/tests/unit/facades/documents.spec.ts
• packages/wasm-sdk/src/queries/document_ranked.rs

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

Ranked-query pins now include contains for selecting one typed-array element. Query guidance, validation text, and tests describe or check this pin form.

Changes: Ranked-query typed-array pins

Layer / File(s)	Summary
Pin contract and validation packages/wasm-sdk/src/queries/document_ranked.rs	The pin type includes contains and Contains. Query documentation and validation text describe the accepted pin forms. A test checks that the TypeScript pin union includes contains and excludes containsAny.
Facade test and query guidance packages/js-evo-sdk/tests/unit/facades/documents.spec.ts, packages/js-evo-sdk/README.md	A facade test checks that a ranked query with a contains pin is forwarded unchanged. The README describes typed-array pins and ranking array elements.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: pastapastapasta

Merge Risk: ⚪ Minimal · up to 874be

The change makes the contains pin available through the generated SDK types, and the added test checks the typed query. No material merge risk remains beyond normal build and test validation.

Pre-merge checks · 5

Passed checks (5 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: allowing a contains pin in the ranked query type.
Docstring Coverage		Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files. (1 skipped: 1 …
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 docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

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

[thepastaclaw]

🕓 Review not started yet because the new head is waiting for the 30-minute push debounce.

• Request normal review — click when the PR is ready for review.
• Request priority review — click to move this review to the front of the queue.

Commit 874be58. Normal review starts when eligible; priority review starts as soon as a slot is available.