Add serialization support for QueryBuilder where/sort/minus clauses

[flyon]

Summary

This PR adds comprehensive serialization and deserialization support for QueryBuilder's where clauses, sort keys, and minus entries. Previously, these complex runtime structures containing live object references could not be round-tripped through JSON. Now they are converted to plain JSON-safe representations that preserve all query semantics.

Key Changes

• New QueryBuilderSerialization.ts module: Provides serialization/deserialization helpers for:

  • WherePath structures (evaluation paths, AND/OR combinations, expression nodes)
  • SortByPath structures (property paths with direction)
  • RawMinusEntry structures (shape references, where clauses, property paths)
  • All nested QueryArg types (primitives, dates, node references, nested where clauses, arg paths)

• Updated QueryBuilder.toJSON():

  • Evaluates where/sort/minus callbacks and serializes the resulting structures
  • Merges preload entries into the FieldSet before serialization for consistent IR
  • Preserves nullSubject and pendingContextName flags
  • Handles both callback-based and pre-evaluated data

• Updated QueryBuilder.fromJSON():

  • Deserializes where/sort/minus clauses back into runtime structures
  • Stores deserialized data in private fields (_where, _sortBy, _rawMinusEntries)
  • Uses deserialized data during build() when callbacks are unavailable
  • Restores nullSubject and pendingContextName flags

• Updated QueryBuilder.build():

  • Falls back to pre-evaluated data when callbacks are not available
  • Enables queries restored from JSON to produce identical IR

• Comprehensive test coverage in serialization.test.ts:

  • Where clause serialization (simple equals, nodeRef args, AND/OR combinations, nested paths)
  • Sort key serialization and round-trip validation
  • Minus entry serialization (shape types and where clauses)
  • Complex round-trip scenarios with multiple clauses
  • Preload serialization and merging behavior
  • JSON string serialization (full stringify/parse cycle)

Implementation Details

• Serialization converts live object references (PropertyShape, ExpressionNode, etc.) to JSON-safe IDs and metadata
• Deserialization reconstructs runtime structures by looking up shapes and properties by ID
• The approach maintains backward compatibility: queries without where/sort/minus clauses serialize/deserialize as before
• Preloads are merged into the FieldSet during serialization, ensuring consistent IR on deserialization
• All round-trip tests verify that sanitize(restored.build()) equals sanitize(original.build())

https://claude.ai/code/session_01P6n2XLm5DSugoa8RWN97yy

[github-actions]

⚠️ No changeset found. If this PR should trigger a release, run npx changeset and commit the generated file.

If this change doesn't need a release (docs, CI config, etc.), you can ignore this message.