feat(llc): add normalizeStringForSort and Filter.raw, fix array matching

[xsahil03x]

Three changes to stream_core, all walls the stream_chat → stream_core migration hit.

Five more were added and taken back out under review. The history is left intact rather than squashed — Considered and dropped is the more useful half of this PR, and three of those five were things the migration plan had recommended before the evidence came in.

normalizeStringForSort

ComparableField compares strings with String.compareTo, which orders by code unit and pushes lowercase-leading and accented names (jhon, Łukasz, Øystein) past Zara. A locally sorted list then disagrees with the one a query returns, which every product hits the moment it sorts by name.

Folding inside ComparableField was considered and rejected: Filter compares through it too, so $eq, $gt and $lt would become case- and diacritic-insensitive locally while the API stayed exact. This is a utility to apply in a SortField value getter instead. Ported from stream_chat with its tests; preserves Japanese, Thai and Vietnamese-specific runes.

Filter.raw

Filter is sealed, so a downstream package cannot add a variant — a gap here has no workaround. The concrete case: a Stream predefined filter is authored server-side and echoed back to the SDK, and GetStream/chat#15657 withdrew $ne and $nin from the published spec without removing them from the query layer, so an echoed filter can legitimately carry an operator core does not model. raw is the fallback leaf that lets a decoder stay total, the way an unrecognised sort field falls back to a custom one.

matches throws for it. Returning true is right under and and wrong under or/nor, where an opaque node would match every record; returning false inverts the problem. Swift resolves this with a nullable predicate and compactMap, dropping nodes it cannot wire, but bool matches(T) has no third state. Refusing is the only outcome that cannot silently produce a wrong result. ComparableField already throws from this layer.

Array-valued fields match element-wise

Filter.equal and Filter.in_ compared a field's value with deep equality, which is order-sensitive for lists. A field whose getter returns a list therefore never matched in practice: $in asked whether the whole list equalled one of the query values, and $eq asked for the same elements in the same order.

Neither is what a query does. Every array field the API exposes — a channel's members and filter_tags, a user's teams, a message's attachments.type — is matched element-wise, comparing as a set for $eq and intersecting for $in. Not one is order-sensitive, so the old behaviour could not agree with any query the API accepts.

An array passed to $in still compares whole, so a value that is itself an array keeps its meaning; only plain values intersect. The $eq test that asserted order-sensitivity is updated, since no query can produce that answer.

Considered and dropped

$nor. Neither StreamCore (Swift) nor stream-android-core models it, and adding it to Dart alone breaks a parity the three otherwise keep. stream-chat-swift depends on StreamCore and keeps its own 671-line Filter, undeprecated, so no chat SDK uses core's filter today. Chat is removing $nor from its own surface rather than pushing it up.

Filter.empty. Nullability covers it, which is how stream_feeds already works: Filter? on the query, defaulted at the request boundary. It is also not merely unused — it serializes to {}, and queryThreads reads request.Filter != nil rather than a length, so a neutral filter is non-nil there and switches the request onto a wider server query while omitting the field does not.

Sort value equality. It compared field.remote and ignored the comparator, so two sorts naming the same wire field with different value getters compared equal and hashed equal while ordering a list in opposite directions. Unfixable while a field carries a closure: comparing the field itself is identity, and closures have no meaningful equality.

SortDirection.fromJson. The generator never calls it. json_serializable uses a fromJson static for class-typed fields, but decodes enums through $enumDecode against the generated map, taking its fallback from @JsonKey(unknownValue:) at each field site. It would have been reachable only by hand, while generated code disagreed with it.

@JsonEnum(valueField:) on SortDirection. Removed a real duplicate, but once fromJson was gone nothing depended on the two declarations agreeing. sort.dart is untouched by this PR.

A per-field isCollection opt-in. The first shape of the array fix, so the default could stay order-sensitive. It needed a new constructor on FilterField and a flag at every collection declaration, to reach behaviour the runtime type already determines — and no API field turned out to want the order-sensitive reading.

Verification

dart analyze --fatal-infos lib test clean, full suite green at 827 tests, up from 812.

The commit count is high for the size of this — the net diff is one new file, one new filter variant, two matches bodies and their tests. Reviewing the diff rather than the commits is the faster path; the commits are there for the rejections.

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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

[codecov]

Codecov Report

❌ Patch coverage is 97.67442% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 68.17%. Comparing base (2aea141) to head (01982a3).

Files with missing lines	Patch %	Lines
...kages/stream_core/lib/src/query/filter/filter.dart	93.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #181      +/-   ##
==========================================
+ Coverage   68.02%   68.17%   +0.14%     
==========================================
  Files         209      210       +1     
  Lines        8554     8597      +43     
==========================================
+ Hits         5819     5861      +42     
- Misses       2735     2736       +1     

☔ View full report in Codecov by Harness.
📢 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.