fix(lens): apply search filters on @optional properties (#170)

[pau-minoves]

Summary

Fixes #170.

A find({ where }) filter on a property declared @optional is silently ignored. The query builder wraps the property in an OPTIONAL block and emits the search FILTER inside that block, where it only leaves the value unbound instead of removing the row — so every resource of the class comes back regardless of the filter.

Root cause

In QueryBuilder.getShape, an @optional property is wrapped in OPTIONAL { ... } and SearchHelper's FILTER is pushed between the opening and closing braces:

OPTIONAL {
  ?iri <…/prop> ?iri_1 .
  FILTER (?iri_1 = "x") .   # only unbinds ?iri_1 — never removes the row
}

Fix

Emit the search FILTER after the OPTIONAL block closes, so it constrains the result set:

OPTIONAL { ?iri <…/prop> ?iri_1 . }
FILTER (!BOUND(?iri_1) || (?iri_1 != "x"))   # $not — keeps resources without the value

Operator polarity is handled explicitly:

• Negative operators ($not, $notIn) are guarded with !BOUND(?v) || (...), so resources that lack the value are kept — "not equal to X" shouldn't drop resources that have no value. This matches the expected output in Search filter on @optional property does not exclude results #170.
• Positive operators ($equals, $gt, $contains, $in, …) are left bare: an unbound value makes the comparison a runtime error, which SPARQL treats as false and correctly excludes the row (a resource without the value cannot match "equals X").

Required (non-optional) properties are unchanged — their FILTER still sits at the top level exactly as before, so existing behavior and tests are unaffected.

Changes

• library/lens/query_builder.ts — move an optional property's search FILTER outside its OPTIONAL block; thread an optional flag to SearchHelper.
• library/lens/search_helper.ts — addFilter guards negative operators with !BOUND(?v) || (...) when the property is optional.
• tests/e2e/search.test.ts — new coverage for $equals / $not / $notIn on an @optional property, including the absent-value (unbound) cases.

Testing

• deno task fmt:check — clean
• deno task lint — clean
• Full test suite: 288 passed, 0 failed (4 new tests added; no existing tests changed).

[karelklima]

Hi @pau-minoves, thanks for the PR!

I will do some internal testing of the functionality before commenting on the code. There is one important thing that I need to consider from the library interface perspective - whether the positive filter on an optional property (e.g. $equals) only match the entity if the property actually exists. Because the current solution, as far as I understand it from briefly reading through the solution, accepts entities that lack such property.

[pau-minoves]

Thanks @karelklima . I'll go by your guidance here. FYI, we have this fixed deployed in production and so far so good.

[karelklima]

I am having trouble merging / verifying this work and publishing a new LDkit version because of upstream issues with esm.sh and Deno. Will try to resolve it soon, but no ETA.

[pau-minoves]

Yep, saw it. No issues.

…

On Wed, Jul 29, 2026 at 5:10 PM Karel Klíma ***@***.***> wrote: *karelklima* left a comment (karelklima/ldkit#176) <#176 (comment)> I am having trouble merging / verifying this work and publishing a new LDkit version because of upstream issues with esm.sh and Deno. Will try to resolve it soon, but no ETA. — Reply to this email directly, view it on GitHub <#176?email_source=notifications&email_token=AAHL42ZHQHZAJXX67GFAX2L5HIHXVA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMJRHE3TGNJWHE4KM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5119735698>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHL423CK26SPNOITCBCQYL5HIHXVAVCNFSNUABFKJSXA33TNF2G64TZHM2DAMBYGAZDCNRSHNEXG43VMU5TIOBUG44TIOJVGQ2KC5QC> . You are receiving this because you were mentioned.Message ID: ***@***.***>