Document the streaming attachment transport (JS SDK) - #563
Open
khawarizmus wants to merge 3 commits into
Open
Conversation
…t SDK - Clarified the format of `localUri` for local storage references. - Added details about the `Attachment Transport` and its role in managing remote operations. - Introduced the concept of a streaming transport for large files, including configuration examples. - Updated notes on the React Native local storage adapter requirements. - Provided additional context on the `Attachment Queue` and its lifecycle management. This update aims to improve clarity and usability for developers working with attachments.
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
benitav
reviewed
Aug 13, 2026
benitav
reviewed
Aug 13, 2026
benitav
reviewed
Aug 13, 2026
benitav
reviewed
Aug 13, 2026
benitav
reviewed
Aug 13, 2026
simolus3
reviewed
Aug 13, 2026
- Updated the description of the remote storage adapter to emphasize the use of streaming transports for large file transfers. - Removed outdated sections on the Attachment Transport, consolidating information for clarity. - Enhanced the explanation of the Attachment Queue and its role in managing attachment lifecycles. - Clarified the handling of `localUri` in the web SDK and its implications for image loading. These changes aim to improve the documentation's clarity and usability for developers working with attachments.
simolus3
reviewed
Aug 21, 2026
| - `downloadFile(attachment)` - Download file from cloud storage | ||
| - `deleteFile(attachment)` - Delete file from cloud storage | ||
|
|
||
| In the JavaScript/TypeScript SDK, apps that transfer large files can replace this adapter with a streaming transport; see [Transferring Large Files Without Buffering](#transferring-large-files-without-buffering). |
Contributor
There was a problem hiding this comment.
Are we calling it TypeScript SDK anywhere else?
Suggested change
| In the JavaScript/TypeScript SDK, apps that transfer large files can replace this adapter with a streaming transport; see [Transferring Large Files Without Buffering](#transferring-large-files-without-buffering). | |
| In the JavaScript SDK, apps that transfer large files can replace this adapter with a streaming transport; see [Transferring Large Files Without Buffering](#transferring-large-files-without-buffering). |
This also still makes it sound like all other SDKs necessarily buffer the file, when that is not true for Kotlin and Dart.
| - **Performs cleanup** - Removes archived files that are no longer needed | ||
| - **Verifies integrity** - Checks local files exist and repairs inconsistencies | ||
|
|
||
| In the JavaScript/TypeScript SDK, remote transfers buffer each file through JS memory by default. Apps that handle large files can swap in a streaming transport adapter; see [Transferring Large Files Without Buffering](#transferring-large-files-without-buffering). |
Contributor
There was a problem hiding this comment.
Let's also only mention this once (it's also mentioned under attachment table, I don't think it belongs there).
| - **Resumable transfers** - The queue retries a failed operation by calling the transport again on the next sync interval. A transport built on a resumable protocol such as [tus](https://tus.io) or S3 multipart upload can continue from the last confirmed offset instead of restarting from zero. Downloads can resume a partial file with HTTP `Range` requests | ||
| - **Encryption** - Encrypt files before upload and decrypt them after download for end-to-end encrypted attachments, without holding the whole file in memory | ||
|
|
||
| ```typescript |
Contributor
There was a problem hiding this comment.
Instead of this empty snippet, linking to the relevant interface in our tsdoc reference might be better.
Comment on lines
+2502
to
+2503
|
|
||
| Throwing from any method marks the operation as failed; the queue retries it on the next sync interval, subject to your [error handler](#error-handling). |
Contributor
There was a problem hiding this comment.
IMO this is obvious enough that it doesn't need to be mentioned.
Suggested change
| Throwing from any method marks the operation as failed; the queue retries it on the next sync interval, subject to your [error handler](#error-handling). |
| // saveFileFromUri queues the upload without reading the file into memory. | ||
| // Requires a streaming-capable local storage adapter (StreamingLocalStorageAdapter: | ||
| // Node.js, Expo, or React Native FS; not available on web). | ||
| async function attachRecording(localUri: string, recordingId: string) { |
Contributor
There was a problem hiding this comment.
Maybe we should add a second snippet for this (to have one with a blob and one streaming example) instead of combining it into one?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the streaming attachment transport shipped in powersync-js powersync-ja/powersync-js#1039 (
@powersync/common@2.1.0), and fixes a few pre-existing issues in the JS examples found along the way.New content (all JavaScript/TypeScript only; other SDK tabs untouched):
AttachmentTransportAdapterinterface, and the either-remoteStorage-or-transportAdapter configuration rulecreateTransportAdapter, with a full Expo examplesaveFileFromUriexample for registering on-disk files without buffering, plusStreamingLocalStorageAdaptercoverage in the Local Storage Adapter sectionFixes:
state === 'SYNCED', butAttachmentStateis a numeric enum, so the checks never matchedProfilePhotoweb example passedlocal_uri(anindexeddb://reference) straight to<img src>, which fails; it now converts through the storage adapter to an object URL, with a note explaining the platform differenceThe content in this PR was AI-assisted using Claude Code.