Skip to content

feat!: root-inheriting predicate combinators; fix docs naming nonexistent methods - #447

Merged
zantvoort merged 4 commits into
mainfrom
fix/phantom-method-docs
Aug 11, 2026
Merged

feat!: root-inheriting predicate combinators; fix docs naming nonexistent methods#447
zantvoort merged 4 commits into
mainfrom
fix/phantom-method-docs

Conversation

@zantvoort

@zantvoort zantvoort commented Aug 11, 2026

Copy link
Copy Markdown
Collaborator

Closes the documentation and error-message drift reported in #406, and completes the #372 join-widening model at the predicate level, which that report surfaced.

Docs and error messages

  • The collection-parameter error in TemplateProcessor now points at real API, whereId(ids) or where(path, IN, values), instead of the nonexistent whereAny/whereAll builder methods.
  • The phantom whereAny convention in the WhereBuilder class docs is replaced with the join-widening model. This also existed in the storm-java21 variant, which the issue did not list, and is fixed there as well.
  • The Kotlin KDoc examples now use whereBuilder { } and the resultList property instead of the Java-only where-lambda and getResultList(), and compile as written against the current API.
  • Copy-pasted javadoc corrected: DbTable specifies the table or view name (optionally its schema), DbColumn the column name, and EQUALS/NOT_EQUALS are labeled =/<> rather than EXISTS/NOT EXISTS.
  • The null guard in Operator moves from the display name, which is never null, to the column parameter via a requireColumn helper in every built-in operator. A null column now throws IllegalArgumentException instead of silently rendering null = ?. The zero-placeholder IN/NOT_IN forms never reference the column and still render their constant expressions.

Predicate combinators inherit the query root

andAny/orAny were the predicate-level Any variants #372 left behind; writing docs that pointed users at them made that visible. They are removed from every API, and and/or follow the clause model: the query root decides what combines.

  • Java (storm-java21): every predicate carries the builder's root, so and/or absorb the Any twins with a ? extends T parameter. A narrow builder combines within the root graph; a join widens the root. Post-feat!: a join widens the query, replacing the Any clause variants #372 the twins had no constructible argument with a foreign root left.
  • Kotlin: and/or move into the whereBuilder { } scope as member extensions bound to the scope's root. A narrow scope combines within the root graph; a join widens the root, and the same expression combines predicates across joined entities, e.g. (petName eq "Leo") and (ownerLastName eq "Davis") after joining Owner. Top-level and/or extensions combine same-rooted predicates outside a scope. A new integration test covers the cross-entity case after a join.
  • Core states the same root-relative contract: and/or take ? extends T, the level where operates at. The bridges present their arguments within the receiver's root, which holds in every sound path: narrow scopes guarantee same-root by their public signatures, and a widened scope's root is Data itself. Query-time validation reports paths on entities outside the query.

Verified with full builds of storm-foundation, storm-core (2603 tests), storm-java21 (541) and storm-kotlin (1714, including the new cross-entity test) on JDK 21, plus a full reactor compile.

Fixes #406

- Point the collection-parameter error at whereId(ids)/where(path, IN, values)
  instead of the nonexistent whereAny/whereAll builder methods.
- Replace the phantom whereAny convention in the WhereBuilder docs (Kotlin and
  Java) with the real cross-table composition via andAny/orAny or custom
  template strings.
- Rewrite Kotlin KDoc examples to use whereBuilder { } and the resultList
  property instead of the Java-only where-lambda and getResultList().
- Fix copy-pasted javadoc on DbTable, DbColumn and the EQUALS/NOT_EQUALS
  operator labels.
- Guard the column parameter in the built-in operators: a null column now
  throws instead of silently rendering "null = ?". The display-name null
  check it replaces was unreachable.

Fixes #406
@codecov

codecov Bot commented Aug 11, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 92.85714% with 2 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
...a/st/orm/core/template/impl/TemplateProcessor.java 0.00% 2 Missing ⚠️

📢 Thoughts on this report? Let us know!

… twins

andAny/orAny were the predicate-level Any variants #372 left behind. The
combinators now follow the same model as the clauses: the query root decides
what combines.

- Java: every predicate carries the builder's root, so and/or absorb the Any
  twins with a ? extends T parameter; a narrow builder combines within the
  root graph and a join widens the root. The twins had no constructible
  argument with a foreign root left.
- Kotlin: and/or move into the whereBuilder { } scope as member extensions
  bound to the scope's root, so a narrow scope combines within the root graph
  and a widened scope combines predicates across joined entities with the
  same syntax. Top-level and/or extensions combine same-rooted predicates
  outside a scope.
- Core keeps a permissive ? extends Data parameter: it is the engine the
  Kotlin bridge feeds mixed-root predicates through, and query-time
  validation reports paths on entities outside the query.
@zantvoort zantvoort changed the title fix: correct docs and error messages that name nonexistent methods feat!: root-inheriting predicate combinators; fix docs naming nonexistent methods Aug 11, 2026
The core and/or parameters tighten from ? extends Data to ? extends T,
the same level where operates at. The bridges' arguments are within the
receiver's root in every sound path: narrow scopes guarantee same-root by
their public signatures, and a widened scope's root is Data itself, so the
permissive parameter stated less than what every caller already proves.
The Kotlin surface had the cross-entity and case; core and storm-java21
predicates on a widened builder were untested, and no surface covered or.
Pets joined with owners: name = 'Leo' AND owner 'Davis' finds Betty's Leo;
OR also admits Harold Davis's Iggy.
@zantvoort
zantvoort merged commit 43e09a5 into main Aug 11, 2026
7 checks passed
@zantvoort
zantvoort deleted the fix/phantom-method-docs branch August 11, 2026 11:58
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.

Error messages and API docs name methods that don't exist

1 participant