Skip to content

refactor: API overhaul for better performance and better utility#88

Merged
jbee merged 38 commits into
mainfrom
object-validation-extension
Mar 26, 2026
Merged

refactor: API overhaul for better performance and better utility#88
jbee merged 38 commits into
mainfrom
object-validation-extension

Conversation

@jbee

@jbee jbee commented Mar 16, 2026

Copy link
Copy Markdown
Contributor

Once again, as in #86 , there were TODOs I wanted to address before I finish with the validation, and it once again become a huge PR with all kinds of improvements.

API Changes

While the core library is still very much the same the API has evolved quite a bit.
Going into all detail changes is too excessive, so this is a list of high level changes.
While API did change in many places it should not be hard to adjust the code calling as semantics are mostly the same.

  • ✨ adds a @TerminalOp annotation purely to make the contract of terminal tree operations more clear
  • ✨ adds Appender API as a rich character output API that JsonAppender and JurlBuilder work with
  • ✨ adds TextualNumber to further defer parsing of complicated decimal numbers to potentially avoid allocation during parsing
  • ✨ support for NaN, Infinity and -Infinity in Json5 automatically wrapping them into a string in JSON (with also automatic parsing that string back to a double when accessed via doubleValue())
  • ✨ upgraded the "non-standard" JSON to be a JSON5-ish input channel now accessed via Json5 API (SPEC added)
  • ✨ upgraded JsonArray and JsonObject from JsonValue to JsonMixed items
  • JsonNode and JsonValue now also are Map.Entrys (which simplified API and avoids entry instance creation during access/iteration)
  • ✨ default type access mapping in JsonAccess for "primitive" types now simply maps the corresponding API method in the JsonValue API (as that now has a string-number-boolean "duality" baked into it)
  • JsonAppender avoid creating intermediate Strings even more (most numbers now also append allocation free)
  • ✨ change to expose array elements and object members as Streamable it now allows callers to either do iterator based consumption or stream based consumption without losing internal knowledge for best performance
  • ✨ messages for input format errors are now more consistent and more informative
  • ✨ addition of JsonSelectable query API supporting JsonSelector based lookups (a JsonPath RFC 9535 inspired feature)
  • JsonNode API now allow to control internal index (cache) behaviour when accessing elements and members (which allow features like lookup or validation API to search without causing much memory consumption through node caching)
  • ✨ unification of probing API between JsonValue API and JsonNode API which now both inherit JsonProbe API (required to unify some operation names between those two APIs that were common but named differently)
  • ✨ no creation of JsonPath#segments() any more during node lookup (did allocate)
  • ✨ upgraded JUON => JURL, a simpler, more clear cut "JSON in the URL" notation, with spec and Jurl API
  • ✨ added some useful methods to Text API
  • ✨ added TextBuilder as a char[] based alternative to StringBuilder (to work well with Text)

Accompanied by lots of new tests.

Support for more Standards

  • The Json5 API now allow to use JSON5-ish input (there are nuances detailed in JSON5-star.md)
  • The JsonSelector is conceptually very close to JsonPath RFC 9535 (again, there are nuances to get a more useful tool with less maintenance burden)

Performance

While the list of changes mostly reads like improving the utility and convenience of the APIs these changes were all informed by improving performance. Mainly though avoiding allocations as much as possible and giving users access to operations in a way that let them do what they want with easy so the operations more often than not do just what was needed to get to the outcome the caller wanted. Another big part is once again to avoid certain problematic JDK methods and utility classes as they unfortunately are not done with performance in mind.

@jbee jbee self-assigned this Mar 16, 2026
@sonarqubecloud

Copy link
Copy Markdown

Quality Gate Failed Quality Gate failed

Failed conditions
2 New issues
2 New Code Smells (required ≤ 0)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

@jbee jbee marked this pull request as ready for review March 26, 2026 09:28
@jbee jbee merged commit 92305a2 into main Mar 26, 2026
2 of 3 checks passed
@jbee jbee deleted the object-validation-extension branch March 26, 2026 09:28
@jbee jbee changed the title feat: JSON validation based on interfaces and records refactor: API overhaul for better performance and better utility Mar 26, 2026
This was referenced Apr 23, 2026
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.

1 participant