Update attachment package #735

joshua-journey-apps · 2025-10-07T10:35:17Z

This a port of the Swift, Dart and Kotlin attachment's API to the JS SDK.

This addresses the following issues #715 and #714 by adding the meta_data column to the table and persisting it in the attachments table.

It is currently still a work-in-progress so there are a couple things that still needs to be done:

changeset-bot · 2025-10-07T10:35:21Z

🦋 Changeset detected

Latest commit: d86799a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@powersync/react-native	Minor
@powersync/common	Minor
@powersync/node	Minor
@powersync/web	Minor
@powersync/attachments	Patch
@powersync/adapter-sql-js	Patch
@powersync/op-sqlite	Patch
@powersync/tanstack-react-query	Patch
@powersync/diagnostics-app	Patch

Not sure what this means? Click here to learn what changesets are.

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

stevensJourney

This looks like a good improvement so far. I've added some comments for some items I spotted.

packages/attachments/src/AttachmentContext.ts

packages/common/src/attachments/AttachmentContext.ts

packages/attachments/src/StorageService.ts

packages/common/src/attachments/SyncingService.ts

packages/attachments/src/StorageService.ts

packages/attachments/src/storageAdapters/NodeFileSystemAdapter.ts

packages/attachments/vitest.config.ts

packages/attachments/src/AttachmentQueue.ts

packages/common/src/attachments/AttachmentQueue.ts

…ile saving.

- Added `getAttachment` method to retrieve an attachment by ID in AttachmentContext. - Updated `upsertAttachment` to handle null values for optional fields. - Introduced `generateAttachmentId` method in AttachmentQueue for generating unique IDs. - Modified `watchActiveAttachments` to accept a throttle parameter. - Added `deleteFile` method to have attachment deletion. - Updated tests to cover new functionality and ensure reliability.

…ttachment sync operations - Added AttachmentErrorHandler interface to manage download, upload, and delete errors for attachments. - Updated AttachmentQueue and SyncingService to utilize the new error handler. - Enhanced tests to verify error handling behavior during attachment sync processes.

…eact Native

…monorepo

…ries

… across the react-native-web demo

# Conflicts: # pnpm-lock.yaml

…ules

stevensJourney

Left some comments. Overall the APIs and code looks good so far.

stevensJourney · 2025-12-04T08:36:34Z

demos/react-native-supabase-todolist/library/powersync/system.ts

+        localStorage,
+        remoteStorage,
+        watchAttachments: (onUpdate) => {
+          this.powersync.watch(


It looks like we would need a way to dispose of the watched queries here. e.g. if the AttachmentsQueue was to be closed (or sync stopped), we'd need to stop these queries.

stevensJourney · 2025-12-04T08:49:54Z

packages/attachments/package.json

    "type": "git",
    "url": "git+https://github.com/powersync-ja/powersync-js.git"
  },
+  "deprecated": "This package has been merged into @powersync/common. Please use @powersync/common instead.",


Maybe we should recommend using the various SDK packages directly instead? We typically don't require users to install @powersync/common directly for most cases.

stevensJourney · 2025-12-04T09:03:03Z

packages/common/src/attachments/AttachmentQueue.ts

+              state: AttachmentState.SYNCED
+            });
+          } else {
+            // The localURI should be set if the record was meant to be downloaded


Suggested change

// The localURI should be set if the record was meant to be downloaded

// The localURI should be set if the record was meant to be uploaded

stevensJourney · 2025-12-04T09:04:47Z

packages/common/src/attachments/AttachmentQueue.ts

+   * - Archives attachments with missing local files that haven't been uploaded
+   * - Requeues synced attachments for download if their local files are missing
+   */
+  verifyAttachments = async (): Promise<void> => {


For my curiosity, whats the reason for this being an arrow function?

stevensJourney · 2025-12-04T09:11:42Z

packages/common/src/attachments/SyncingService.ts

+        hasSynced: true
+      };
+    } catch (error) {
+      const shouldRetry = this.errorHandler?.onUploadError(attachment, error) ?? false;


I think the default here should be true. We only want to skip retries if the errorHandler explicitly says to do so.

stevensJourney · 2025-12-04T09:14:15Z

packages/common/tests/attachments.test.ts

@@ -0,0 +1,481 @@
+import { describe, expect, it, vi } from 'vitest';
+import { vol } from 'memfs';
+import { PowerSyncDatabase, Schema, Table, column, NodeFileSystemAdapter } from '../../node';


It might be easier to just have these tests in the node package's unit tests.

stevensJourney · 2025-12-04T09:15:45Z

packages/react-native/package.json

  "dependencies": {
    "@powersync/common": "workspace:*",
    "@powersync/react": "workspace:*",
+    "expo-file-system": "18.0.12",


I assume this would not work on non-Expo React Native projects? One would need to confirm this dependency does not cause any issues on bare React native projects.

joshua-journey-apps added 5 commits October 6, 2025 15:40

initial implementation

01070e1

Add make, remove and get uri endpoints to local storage

23dc8e4

Fix exporting node and index db storage adapters

ecb71cb

Wip add sync throttle & cache limiting

029df9d

Add downloading attachment test

958675a

joshua-journey-apps requested a review from stevensJourney October 7, 2025 10:35

stevensJourney reviewed Oct 21, 2025

View reviewed changes

joshuabrink and others added 17 commits October 27, 2025 15:49

Add user defined storage adapter path

45773aa

Refactor watch active observer into dedicated service

533dfab

Add temporal units to variable name

643289d

Rename storage -> syncing service

6840fb0

Add updateHook to save file

d8d4ad9

Use async onUpdate callback

9509aeb

Improve comments

9ac685c

Fix closing the watch active attachments listener

ce33bab

tests(WIP:) initial node setup and few bug fixes

704c2a8

tests: fixed SyncService to rely on LocalStorage and be agnostic to f…

ff25b2b

…ile saving.

feat: added archival management to AttachmentQueue via AttachmentContext

ec1a733

docs: update README.md to document usage

f6b2343

feat: added ExpoFileSystemAdapter to the attachments package

4cb5753

refactor: refactored react native demo to use new attachments API

7e40d26

fix: expo blob compatability and attachment row mapping

206bd5f

joshuabrink force-pushed the attachment-package-refactor branch from 671e23a to bea28d9 Compare November 12, 2025 09:15

fix: node exclusive exports

e42ae45

joshuabrink force-pushed the attachment-package-refactor branch from bea28d9 to e42ae45 Compare November 12, 2025 09:15

fix: linting, dead code and move active watch into start sync

4d5a1bc

khawarizmus mentioned this pull request Nov 19, 2025

docs: revamp the attachment documentation powersync-ja/powersync-docs#289

Open

8 tasks

joshuabrink and others added 15 commits November 20, 2025 12:13

refactor: move attachments to common package

8db8f2a

refactor: moved readme to attachments folder

be856e9

refactor: add ExpoFileSystemAdapter for local storage management in R…

c3fd550

…eact Native

fix: export IndexDBFileSystemAdapter from web package

26722fb

chore: add helper script to clean up node_modules directories in the …

3eba6f0

…monorepo

docs: fixed README to properly point to React Native web demo

de9130e

refactor: demos now use attachments functionality from the core libra…

20bb3a3

…ries

refactor: migrate to using @powersync/common for shared functionality…

b8dea39

… across the react-native-web demo

fix: exclude expo file system from bundle

62b0bdc

Merge branch 'main' into attachment-package-refactor

d514ef8

# Conflicts: # pnpm-lock.yaml

Merge branch 'main' into attachment-package-refactor

649290c

fix: add missing comma in package.json dependencies

eb0a93a

chore: update dependencies in pnpm-lock.yaml to latest versions

d179b9c

fix: update import paths in attachment-related files to use local mod…

f401bc0

…ules

chore: add changeset

d86799a

joshuabrink marked this pull request as ready for review November 28, 2025 13:10

khawarizmus requested a review from stevensJourney December 1, 2025 07:02

stevensJourney reviewed Dec 4, 2025

View reviewed changes

	// The localURI should be set if the record was meant to be downloaded
	// The localURI should be set if the record was meant to be uploaded

Update attachment package #735

Are you sure you want to change the base?

Update attachment package #735

Conversation

joshua-journey-apps commented Oct 7, 2025 • edited by khawarizmus Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

stevensJourney left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stevensJourney left a comment

Choose a reason for hiding this comment

Uh oh!

stevensJourney Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

stevensJourney Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

stevensJourney Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

stevensJourney Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

stevensJourney Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

stevensJourney Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

stevensJourney Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

joshua-journey-apps commented Oct 7, 2025 •

edited by khawarizmus

Loading

changeset-bot bot commented Oct 7, 2025 •

edited

Loading