From a355528fa9430196aea815ddbbaa2b91580560fd Mon Sep 17 00:00:00 2001 From: benitav Date: Fri, 3 Oct 2025 15:20:26 +0200 Subject: [PATCH] Improve discoverability, wording polish and fix inaccuracies --- .../powersync_attachments_helper/README.md | 18 ++++++++++++------ packages/powersync_core/doc/attachments.md | 6 ++---- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/packages/powersync_attachments_helper/README.md b/packages/powersync_attachments_helper/README.md index 9ae81747..fdd46803 100644 --- a/packages/powersync_attachments_helper/README.md +++ b/packages/powersync_attachments_helper/README.md @@ -1,11 +1,19 @@ # PowerSync Attachments Helper for Dart/Flutter -[PowerSync Attachments Helper](https://pub.dev/packages/powersync_attachments_helper) is a package that assist in keeping files in sync with local and remote storage. +[PowerSync Attachments Helper](https://pub.dev/packages/powersync_attachments_helper) is a package that assists in keeping files in sync between local and remote storage. > [!WARNING] -> There is a new attachments helper library in the core PowerSync package, available under -> `package:powersync_core/attachments/attachments.dart`. While this package will continue to receive -> bugfixes, new feature development will only happen in the other package. +> This package will eventually be replaced by a new attachments helper library in the core PowerSync package, available through: +> ```dart +> package:powersync_core/attachments/attachments.dart +> ``` +> +> The `powersync_core/attachments` library is in alpha and brings improved APIs and functionality that is more in line with our other SDKs, such as the ability to write your own local storage implementation. +> +> Check out the [docs here](/packages/powersync_core/doc/attachments.md) to get started. +> +> While the `powersync_attachments_helper` package will still get bug fixes if you need them, +> new features will only be developed on `powersync_core/attachments`. ## Features @@ -89,5 +97,3 @@ initializeAttachmentQueue(PowerSyncDatabase db) async { await attachmentQueue.init(); } ``` - -See our [Supabase Flutter To-Do List example app](../../demos/supabase-todolist/README.md) for a concrete implementation of the above. diff --git a/packages/powersync_core/doc/attachments.md b/packages/powersync_core/doc/attachments.md index aad9b5cb..67383942 100644 --- a/packages/powersync_core/doc/attachments.md +++ b/packages/powersync_core/doc/attachments.md @@ -5,7 +5,7 @@ PowerSync. Embedding this data directly in your source databases is [inefficient and not recommended](https://docs.powersync.com/usage/use-case-examples/attachments). Instead, the PowerSync SDK for Dart and Flutter provides utilities you can use to _reference_ this binary data -in your primary data model, and then download it from a secondary data store such as S3. +in your local database, and then download it from a secondary data store such as Supabase Storage or S3. Because binary data is not directly stored in the source database in this model, we call these files _attachments_. ## Alpha release @@ -31,8 +31,7 @@ The attachments' state is stored in a local-only attachments table. ### Example implementation -See the [supabase todolist](https://github.com/powersync-ja/powersync.dart/tree/main/demos/supabase-todolist) demo for -a basic example of attachment syncing. +See the [supabase-todolist](https://github.com/powersync-ja/powersync.dart/tree/main/demos/supabase-todolist) demo for a basic example of attachment syncing. ### Setup @@ -77,7 +76,6 @@ final attachmentQueue = AttachmentQueue( ``` Here, - - An instance of `LocalStorageAdapter`, such as the `IOLocalStorage` provided by the SDK, is responsible for storing attachment contents locally. - An instance of `RemoteStorageAdapter` is responsible for downloading and uploading attachment contents to the secondary