feature: add subscription.find

[dblythy]

Pull Request

• Report security issues confidentially.
• Any contribution is under this license.
• Link this pull request to an issue.

Issue

https://github.com/parse-community/parse-server/pull/9864

Closes: #2114

Approach

Tasks

• [ ] Add tests
• [ ] Add changes to documentation (guides, repository pages, code comments)

Summary by CodeRabbit

• New Features

  • Subscriptions can now request query results on-demand and receive batched "result" events containing parsed objects.
  • Subscriptions may be linked to the live client to enable sending queries.

• Tests

  • Added coverage for handling "result" events, missing class names in payloads, and the on-demand query flow.

• Documentation

  • Type definitions and JSDoc updated to document the new subscription client linkage, constructor signature, and the find/result API.

[parse-github-assistant[bot]]

🚀 Thanks for opening this pull request!

[coderabbitai[bot]]

[!WARNING]

Rate limit exceeded

@dblythy has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 5 minutes and 36 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between b0aa37518c24b4fbfdce500d8849e18e4cb97fa8 and fae55120fe9e36ce725dc1f8d135a196a272f685.

📒 Files selected for processing (1)

• types/LiveQueryClient.d.ts (1 hunks)

📝 Walkthrough

Walkthrough

Adds QUERY op and RESULT event handling to LiveQueryClient, passes client reference into LiveQuerySubscription, implements subscription.find() to send a QUERY via WebSocket, maps RESULT payloads to ParseObject instances (setting className when missing) and emits them on the subscription, and updates types and tests accordingly.

Changes

Cohort / File(s)	Summary
LiveQuery client ops & events src/LiveQueryClient.ts	Adds OP_TYPES.QUERY, OP_EVENTS.RESULT, and SUBSCRIPTION_EMMITER_TYPES.RESULT; strengthens typings (constructor, on/emit, generateInterval); constructs subscriptions with a client reference; handles incoming RESULT messages by mapping data.results to ParseObject (assign className from subscription query if missing) and emits 'result' on the subscription.
Subscription client plumbing & query API src/LiveQuerySubscription.ts	Adds public client field; updates constructor to accept optional client; adds find() which waits for client.connectPromise and sends a QUERY operation over the client's socket using the subscription id as requestId (no-op when client absent).
Type declarations types/LiveQuerySubscription.d.ts	Declares client: any; updates constructor signature to (..., client?: any); adds find(): void with documentation indicating results are delivered via the 'result' event.
Tests for result flow and find() src/__tests__/LiveQueryClient-test.js	Adds tests confirming LiveQuerySubscription.prototype.find exists; verifies subscription find() sends correct QUERY payload; adds tests simulating WebSocket RESULT messages (with and without className) and asserting proper mapping and 'result' emission.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor App as Application
  participant Sub as LiveQuerySubscription
  participant LQC as LiveQueryClient
  participant WS as WebSocket
  participant PS as ParseServer

  App->>Sub: subscription.find()
  alt client attached
    Sub->>LQC: await connectPromise
    LQC->>WS: send OP_TYPES.QUERY { requestId: sub.id, query, sessionToken }
    WS->>PS: forward QUERY
    PS-->>WS: RESULT { requestId, results:[...] }
    WS-->>LQC: message(OP_EVENTS.RESULT, { requestId, results })
    LQC->>LQC: map results -> ParseObject (set className if missing)
    LQC->>Sub: emit('result', [ParseObject,...])
    Sub-->>App: 'result' event with mapped results
  else no client
    Sub-->>App: find() is no-op
  end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Potential focus areas:

• Correctness of RESULT -> ParseObject mapping and className assignment.
• Timing around client.connectPromise, socket state, and error handling in find().
• Memory/lifecycle implications of storing client on subscriptions.
• Type signature updates in LiveQueryClient constructor and on/emit wrappers to ensure compatibility with consumers.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "feature: add subscription.find" is concise, specific, and clearly describes the main change in the changeset. It accurately summarizes the primary feature being introduced - a new find() method on LiveQuerySubscription that enables executing queries through a live query subscription. The title is not vague or misleading and a developer reviewing the repository history would understand that this PR adds subscription query functionality.
Linked Issues Check	✅ Passed	The linked issue #2114 outlines two proposed approaches: Alternative 1 adds methods like subscription.find() to return query results, and Alternative 2 allows running queries independently through a LiveQueryClient. This PR implements Alternative 1 completely, adding the find() method to LiveQuerySubscription and enabling result event delivery through the WebSocket connection. The implementation adds proper RESULT event handling, type support, comprehensive tests, and TypeScript declarations. Alternative 2 (client.querySubscribe) is not implemented, but the issue uses "and/or" language indicating either approach satisfies the core requirement of enabling query execution through the WebSocket connection.
Out of Scope Changes Check	✅ Passed	All code changes are directly aligned with the objective in issue #2114 of enabling query results through subscriptions. The changes include: adding QUERY operation and RESULT event types to support the protocol, enhancing type annotations for better development experience, implementing WebSocket result message handling, adding the new find() method and client reference to LiveQuerySubscription, and comprehensive test coverage. No changes appear to address unrelated concerns or drift outside the scope of implementing subscription-based query execution.
Description Check	✅ Passed	The PR description fills out most of the required template sections: it includes the security reporting and license links, provides links to related issues (https://github.com/parse-community/parse-server/pull/9864 and closes #2114), and includes the tasks checklist. However, the Approach section is completely empty, leaving no explanation of what changes were made or why. This is a significant omission that reduces clarity about the implementation details, though the critical linking information and task checklist are present.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[parseplatformorg]

:white_check_mark: Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
:white_check_mark:	Open Source Security	0	0	0	0	0 issues

:computer: Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[codecov[bot]]

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 99.88%. Comparing base (17e2a77) to head (fae5512). :warning: Report is 44 commits behind head on alpha.

Additional details and impacted files

@@             Coverage Diff             @@
##             alpha    #2735      +/-   ##
===========================================
- Coverage   100.00%   99.88%   -0.12%     
===========================================
  Files           63       64       +1     
  Lines         6185     6233      +48     
  Branches      1456     1492      +36     
===========================================
+ Hits          6185     6226      +41     
- Misses           0        7       +7     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• :package: JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.