[Drift] JS SDK ships new checkpoint-request protocol; Checkpoint Requests doc's linked "in progress" PR is now merged (powersync-js #1072)

[benitav]

What's changing: The JS SDKs gain an opt-in replacement for the /write-checkpoint2.json write-checkpoint protocol: a new POST /sync/checkpoint-request endpoint that fixes two correctness issues in the old sequence-based approach (state that could never be deleted, and disruption when a client switches (device_id, user_id)). This is preparatory protocol work only. Per the PR author, it does not add the client-facing Checkpoint Requests feature (requestCheckpoint()/waitForSync()) to the JS SDKs; that is planned as a separate follow-up PR. It also adds an optional postCheckpointRequest method to backend connectors, for custom checkpoint requests.

High priority — existing docs are now inaccurate or incomplete

• Sync Catch-Up (Checkpoint Requests) (client-sdks/advanced/checkpoint-requests.mdx → https://docs.powersync.com/client-sdks/advanced/checkpoint-requests) — the page's opening Warning reads: "Checkpoint requests are an alpha API and may change. Client support is currently available for Swift and requires PowerSync Service version 1.24.0 or later. Support for the JavaScript SDKs is in progress, and other SDKs will follow." That link now points to a merged PR, but the PR itself does not add JS support for requestCheckpoint()/checkpoint requests — its author explicitly deferred that to a follow-up PR. A reader who follows the "in progress" link and sees it merged could conclude JS support has shipped, when it has not.

For reviewer consideration — worth documenting

• The PR adds an optional postCheckpointRequest method to JS PowerSyncBackendConnector implementations, mirroring the CustomCheckpointRequestConnector.postCheckpointRequest pattern the checkpoint-requests page already documents for Swift (its "Swift Connector" section). No page documents this for JS yet. Once the actual JS checkpoint-requests feature lands (the deferred follow-up this PR mentions), a "JavaScript Connector" section analogous to the existing Swift one would be needed.

Related: #543 (closed 2026-08-12) covered the service-side /sync/checkpoint-request endpoint (powersync-service#696). This PR is the JS client's adoption of that same protocol groundwork — a different source PR and a different angle (client-side opt-in and connector changes), not a duplicate of that issue.

Source PR: powersync-ja/powersync-js#1072. Merged 2026-08-18.

Filed automatically by Claude Code (claude-sonnet-5). A human must verify the scope, prepare the docs PR, and publish it only once this update has been released.

[benitav]

Related PR: powersync-ja/powersync-js#1073 (open, "Product Visibility" label, as of 2026-08-18) looks like the follow-up this issue anticipated. It adds the actual client-facing feature that #1072 only laid protocol groundwork for: requestCheckpoint() on CommonPowerSyncDatabase, returning a CheckpointRequest with hasSynced and waitForSync({ signal }), gated behind the new checkpointMode: 'requests' ConnectOptions value (both marked @alpha). It also wires this through SharedWebStreamingSyncImplementation/SharedSyncImplementation for the web SDK's shared worker.

Once this merges, the checkpoint-requests.mdx Warning ("Client support is currently available for Swift... Support for the JavaScript SDKs is in progress") would need updating to reflect that JS support has landed, and the doc's Swift-only code samples (requestCheckpoint()/waitForSync(timeout:), .requests() connect option) would need a JS-equivalent alongside them — the JS API shape differs slightly (waitForSync({ signal }) uses an AbortSignal rather than a timeout, and checkpointMode: 'requests' is a string option rather than .requests()). This PR does not add a postCheckpointRequest/custom-checkpoint-connector equivalent for JS, so the "For reviewer consideration" item already noted in this issue still stands separately.

Filed automatically by Claude Code (claude-sonnet-5). A human must verify the scope, prepare the docs PR, and publish it only once this update has been released.

---

Generated by Claude Code

[benitav]

[Status Update] Source PR powersync-ja/powersync-js#1073 is now merged on 2026-08-19. This is the follow-up flagged in the previous comment — it adds the actual client-facing requestCheckpoint()/CheckpointRequest API for JS, so the checkpoint-requests.mdx Warning's "Support for the JavaScript SDKs is in progress" line is now stale on top of the JS SDK's checkpoint-request support having landed at all. Documentation updates (including real JS code samples alongside the existing Swift ones) can be published after this ships in a release.

Filed automatically by Claude Code (claude-sonnet-5). A human must verify the scope, prepare the docs PR, and publish it only once this update has been released.

---

Generated by Claude Code

[benitav]

AFAIK the work has been merged, but not yet released, so the message is still accurate for now.

[benitav]

Related activity: powersync-kotlin#371 (open, not yet merged as of 2026-08-20, labeled "Product Visibility") adds opt-in client support for the checkpoint request protocol to the Kotlin SDK. The PR description explicitly calls it out as similar to the JS PR this issue tracks. Once it merges, the checkpoint-requests.mdx Warning ("Client support is currently available for Swift... other SDKs will follow") will need to add Kotlin alongside the JS gap already noted above, and if the Kotlin implementation adds a connector method for custom checkpoint requests (mirroring the existing "Swift Connector" section), a "Kotlin Connector" section would be needed too. Noting it here rather than filing separately since it's the same doc surface and feature family.

Filed automatically by Claude Code (claude-sonnet-5). A human must verify the scope, prepare the docs PR, and publish it only once this update has been released.

---

Generated by Claude Code