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: 9812964

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.

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

packages/attachments/package.json

packages/common/src/attachments/AttachmentQueue.ts

packages/common/src/attachments/SyncingService.ts

packages/common/tests/attachments.test.ts

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.

It requires an expo project unfortunately. But, currently looking at @dr.pogodin/react-native-fs an active fork of react-native-fs, which works on native.

One question about including it as a direct dependency. I was thinking of going the dynamic import + optional peer dependency route (similar to react-native-quick-sqlite), you see any potential pitfalls?

I've seen before, in the past, that nested direct dependencies sometimes aren't detected and installed correctly in the Expo build process. This might have changed at some point though.
Generally, an optional peer dependency would follow our current patterns. Dynamic imports with Metro have been a pain in the past, however if one follows the same patters as React Native Quick SQLite, I think we should be fine.

I kept both, just for better coverage. I think catering for both Expo and vanilla React Native projects would be worthwhile. I understand there is a maintenance burden with supporting both adapters.

The vanilla implementation works on Expo as well, so let me know if you think this is redundant.

stevensJourney

I noticed a few items in this review, but I do think this is looking good.

stevensJourney · 2025-12-15T08:52:00Z

packages/common/src/attachments/AttachmentQueue.ts

+   * @param onUpdate - Callback to invoke when attachment references change
+   * @throws Error indicating this method must be implemented by the user
+   */
+  watchAttachments(onUpdate: (attachment: WatchedAttachmentItem[]) => Promise<void>, signal: AbortSignal): void {


This looks a bit weird as a function definition with no actual implementation. This should probably be a class property instead (since it's assigned in the constructor)

stevensJourney · 2025-12-15T08:54:51Z

packages/common/src/attachments/AttachmentQueue.ts

+  /** Adapter for remote file storage operations */
+  remoteStorage: RemoteStorageAdapter;
+
+  /** @deprecated Directory path for storing attachments  */


Since this is a new version of the implementation which originates from a new source (the SDK packages themselves). I don't think we need to be deprecating things at this point - rather remove them.

stevensJourney · 2025-12-15T08:56:59Z

packages/common/src/attachments/AttachmentQueue.ts

+ */
+export class AttachmentQueue {
+  /** Timer for periodic synchronization operations */
+  periodicSyncTimer?: ReturnType<typeof setInterval>;


The default here for these class members is public - which I think we should avoid for some of these items. For items which make sense to be public, maybe consider making them readonly or clearly handle/document their update behaviour.

stevensJourney · 2025-12-15T08:59:33Z

packages/common/src/attachments/AttachmentQueue.ts

+    this.syncThrottleDuration = syncThrottleDuration;
+    this.archivedCacheLimit = archivedCacheLimit;
+    this.downloadAttachments = downloadAttachments;
+    this.context = new AttachmentContext(db, tableName, logger ?? db.logger, archivedCacheLimit);


One of the main purposes of the AttachmentService is to provide a locked/exclusive access to an AttachmentContext. Creating a context manually here defeats that purpose, please add a withContext method to AttachmentService which provides leased access to the context.

stevensJourney · 2025-12-15T09:00:13Z

packages/common/src/attachments/AttachmentQueue.ts

+  tableName?: string;
+
+  /** Logger instance for diagnostic information */
+  logger?: ILogger;


You can remove the optionality of this member since the constructor provides a default

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

packages/react-native/package.json

  "homepage": "https://docs.powersync.com/",
  "peerDependencies": {
    "@journeyapps/react-native-quick-sqlite": "^2.4.9",
+    "@dr.pogodin/react-native-fs": "^2.36.1",


These should probably also be devDependencies. This probably currently works since the packages are being hoisted from the demos. This will soon no-longer be the case.

stevensJourney · 2025-12-15T09:05:06Z

packages/react-native/rollup.config.mjs

      'js-logger',
      'react-native',
      'react',
+      '@dr.pogodin/react-native-fs',


Should probably also include expo-filesystem here?

stevensJourney · 2025-12-15T09:06:39Z

packages/react-native/src/attachments/ReactNativeFileSystemAdapter.ts

+import { decode as decodeBase64, encode as encodeBase64 } from 'base64-arraybuffer';
+import { AttachmentData, EncodingType, LocalStorageAdapter } from '@powersync/common';
+
+try {


Is it possible to lazy load RNFS in the constructor of ReactNativeFileSystemStorageAdapter instead of doing this globally?

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

joshuabrink added 9 commits December 9, 2025 12:48

chore: update deprecation message

08e062f

fix: should retry handling error as default

0886ae0

chore: move attachment tests to node package

871d3dd

chore: fix comment

3b6a8fe

chore: conform verifyAttachments to normal function

e9ac51a

feat: add abortable attachment watchers

ecd22e5

feat: add vanilla react native storage adapter

8cfc680

fix: web attachment display using blob url

aec02b1

fix: export expo fs adapter

9812964

stevensJourney reviewed Dec 15, 2025

View reviewed changes

Update attachment package #735

Are you sure you want to change the base?

Update attachment package #735

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stevensJourney left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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