add searchableJson query type for automatic operation inference

[tobyhede]

Summary by CodeRabbit

• New Features

  • Added a new searchableJson query type for JSON-based searchable encryption
  • Automatic inference of query operations from plaintext types (strings, objects, arrays)
  • Support for batch queries mixing plaintext types and nulls

• Tests

  • Comprehensive test coverage for searchableJson behavior and inference logic
  • Tests for validation scenarios and mixed explicit/implicit query specifications

[changeset-bot]

⚠️ No Changeset found

Latest commit: 25b0580

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new searchableJson QueryType with mapping to ste_vec and implements inference of the underlying query operation from plaintext (strings → selector, objects/arrays → term), updates index-type resolution logic, and adds comprehensive tests covering plaintext varieties, batch behavior, and error cases.

Changes

Cohort / File(s)	Summary
Type Definitions packages/protect/src/types.ts	Adds searchableJson to QueryTypeName, queryTypes discriminator, and queryTypeToFfi mapping (searchableJson → ste_vec).
Query Inference Logic packages/protect/src/ffi/helpers/infer-index-type.ts	Special-case handling for queryType === 'searchableJson': when plaintext is provided infer queryOp via plaintext type (string → selector, object/array → term); if plaintext is null/undefined return only indexType.
Tests packages/protect/__tests__/encrypt-query-searchable-json.test.ts, packages/protect/__tests__/infer-index-type.test.ts	Adds extensive tests validating searchableJson auto-inference, handling of null/number/boolean/scalars, nested objects/arrays, batch mixed types, ste_vec index requirement, returnType formats, and withLockContext exposure.

Sequence Diagram(s)

sequenceDiagram
  participant Client as ProtectClient
  participant Resolver as InferIndexType
  participant FFI as ste_vec FFI
  participant DB as Database

  Client->>Resolver: resolveIndexType(column, queryType='searchableJson', plaintext)
  alt plaintext is string
    Resolver-->>Client: indexType='ste_vec', queryOp='ste_vec_selector'
  else plaintext is object/array
    Resolver-->>Client: indexType='ste_vec', queryOp='ste_vec_term'
  else plaintext is null/undefined
    Resolver-->>Client: indexType='ste_vec' (no queryOp)
  end
  Client->>FFI: encryptQuery(payload with indexType, queryOp?)
  FFI->>DB: store/encrypt using ste_vec semantics
  DB-->>FFI: ack
  FFI-->>Client: encrypted result

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Add queryOp inference from plaintext for searchableJson #280: Implements searchableJson queryOp inference from plaintext and related resolveIndexType wiring.
• Schema .searchableJson() Implementation #277: Adds schema-side searchableJson column support (casts/index setup) that pairs with this client inference.
• encryptQuery API to support STE Vec operations #279: Overlapping changes to encryptQuery/batch handling and searchableJson/ste_vec inference and tests.

Suggested reviewers

• coderdan
• calvinbrewer

Poem

🐰 I nibble through JSON, sniffing types with delight,
Strings hop to selectors, objects tumble to terms at night—
ste_vec hums a tune, encrypting each quest,
Rabbity tests cheer loudly: the inference is blessed! 🥕✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and clearly describes the main change: adding a new 'searchableJson' query type that performs automatic operation inference based on plaintext types.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch searchable-json

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[tobyhede]

@CodeRabbit full review

[coderabbitai]

✅ Actions performed

Full review triggered.