feat(PowerSync): add attachments support

.changeset/clean-query-ownership.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/query-db-collection': patch
+---
+
+Clean up empty query ownership state while preserving authoritative empty results and retained-row lifecycle behavior.

.changeset/curly-planets-lead.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/powersync-db-collection': patch
+---
+
+Add attachments support via `TanStackDBAttachmentQueue`. This extends the PowerSync SDK's `AttachmentQueue` and backs it with
+a TanStack DB collection, so file uploads/deletes are managed atomically alongside the relational data.

.changeset/young-cats-initialize.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/query-db-collection': minor
+---
+
+Add eager collection support for TanStack Query `initialData` and `initialDataUpdatedAt`, including wrapped response projection and collection-local initialization on shared QueryClient instances.
+
+QueryClient-default `placeholderData` no longer materializes as collection rows, and QueryClient-default `initialData` no longer seeds on-demand subset observers.

CONTRIBUTING.md

@@ -0,0 +1,146 @@
+# Contributing
+
+## Questions
+
+If you have questions about implementation details, help, or support, please use our dedicated community forum at [GitHub Discussions](https://github.com/TanStack/db/discussions). **PLEASE NOTE:** If you choose to open an issue for your question instead, your issue may be closed and redirected to the forum.
+
+## Reporting issues
+
+If you have found what you think is a bug, please [file an issue](https://github.com/TanStack/db/issues/new/choose). **PLEASE NOTE:** Issues that are identified as implementation questions or non-issues may be closed and redirected to [GitHub Discussions](https://github.com/TanStack/db/discussions).
+
+## Suggesting new features
+
+If you are here to suggest a feature, first create an issue if it does not already exist. From there, we can discuss use cases for the feature and how it could be implemented.
+
+## Development
+
+If you have been assigned to fix an issue or develop a new feature, please follow these steps to get started:
+
+- Fork this repository.
+- Use the Node.js version mentioned in `.nvmrc`.
+
+  ```bash
+  nvm use
+  ```
+
+- Enable [Corepack](https://nodejs.org/api/corepack.html) so the [pnpm](https://pnpm.io/) version mentioned in `package.json` is used.
+
+  ```bash
+  corepack enable
+  ```
+
+- Install dependencies.
+
+  ```bash
+  pnpm install
+  ```
+
+- Build all packages.
+
+  ```bash
+  pnpm build
+  ```
+
+- Run tests.
+
+  ```bash
+  pnpm test
+  ```
+
+- Run linting.
+
+  ```bash
+  pnpm lint
+  ```
+
+- Implement your changes and tests in the relevant package or example.
+- Document your changes in the appropriate doc page.
+- Git stage your required changes and commit them.
+- Submit a PR for review.
+
+### Editing the docs locally and previewing changes
+
+The documentation for all TanStack projects is hosted on [tanstack.com](https://tanstack.com), which is a TanStack Start application (https://github.com/TanStack/tanstack.com). You need to run this app locally to preview your changes in the `TanStack/db` docs.
+
+> [!NOTE]
+> The website fetches doc pages from GitHub in production, and searches for them at `../db/docs` in development. Your local clone of `TanStack/db` needs to be in the same directory as the local clone of `TanStack/tanstack.com`.
+
+You can follow these steps to set up the docs for local development:
+
+1. Make a new directory called `tanstack`.
+
+```sh
+mkdir tanstack
+```
+
+2. Enter that directory and clone the [`TanStack/db`](https://github.com/TanStack/db) and [`TanStack/tanstack.com`](https://github.com/TanStack/tanstack.com) repos.
+
+```sh
+cd tanstack
+git clone git@github.com:TanStack/db.git
+# We probably don't need all the branches and commit history
+# from the `tanstack.com` repo, so let's just create a shallow
+# clone of the latest version of the `main` branch.
+# Read more about shallow clones here:
+# https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/#user-content-shallow-clones
+git clone git@github.com:TanStack/tanstack.com.git --depth=1 --single-branch --branch=main
+```
+
+> [!NOTE]
+> Your `tanstack` directory should look like this:
+>
+> ```text
+> tanstack/
+>    |
+>    +-- db/ (<-- this directory cannot be called anything else!)
+>    |
+>    +-- tanstack.com/
+> ```
+
+3. Enter the `tanstack/tanstack.com` directory, install the dependencies, and run the app in dev mode.
+
+```sh
+cd tanstack.com
+pnpm i
+# The app will run on http://localhost:3000 by default
+pnpm dev
+```
+
+4. Visit http://localhost:3000/db/latest/docs/overview in the browser and see the changes you make in `tanstack/db/docs` there.
+
+> [!WARNING]
+> You will need to update `docs/config.json` if you add a new documentation page.
+
+### Running examples
+
+- Make sure you've installed dependencies in the repo's root directory.
+
+  ```bash
+  pnpm install
+  ```
+
+- If you want to run an example against your local changes, run the relevant package build/watch command from the repo root if needed. Otherwise, examples may run against the latest published TanStack DB release.
+
+- Run the example from the selected example directory.
+
+  ```bash
+  pnpm dev
+  ```
+
+#### Note on standalone execution
+
+If you want to run an example without installing dependencies for the whole repo, follow the instructions from the example's README.md file. It will then run against the latest TanStack DB release.
+
+## Changesets
+
+This repo uses [Changesets](https://github.com/changesets/changesets) to automate releases. If your PR should release a new package version (patch, minor, or major), please run `pnpm changeset` and commit the generated file. If your PR affects docs, examples, styles, etc., you probably don't need to generate a changeset.
+
+## Pull requests
+
+Maintainers merge pull requests by squashing all commits and editing the commit message if necessary using the GitHub user interface.
+
+Use an appropriate commit type. Be especially careful with breaking changes.
+
+## Releases
+
+For each new commit added to `main`, a GitHub Workflow is triggered which runs the [Changesets Action](https://github.com/changesets/action). This generates a preview PR showing the impact of all changesets. When this PR is merged, the package will be published to npm.

docs/collections/powersync-collection.md

@@ -1099,4 +1099,171 @@ const liveQuery = createLiveQueryCollection({
         completed: todo.completed,
       })),
 })
+```
+
+## Attachments
+
+`@tanstack/powersync-db-collection` ships `TanStackDBAttachmentQueue`, an [`AttachmentQueue`](https://docs.powersync.com/usage/use-case-examples/attachments-files) whose file operations commit inside a TanStack DB collection transaction. This lets you create (or delete) an attachment and mutate a related collection row (for example, setting `lists.photo_id`) atomically in a single transaction, instead of issuing two independent writes.
+
+The queue extends PowerSync's `AttachmentQueue`, so the generic concepts are unchanged and documented once in the SDK.
+
+> This section only covers what is specific to the TanStack DB integration. For storage adapters (local and remote), the `AttachmentTable` schema primitive, error-handling/retry semantics, and the `startSync()` / `stopSync()` lifecycle, see the [PowerSync attachments documentation](https://docs.powersync.com/usage/use-case-examples/attachments-files).
+
+### Prerequisites
+
+These are standard PowerSync attachment requirements. See the SDK attachments docs for details.
+
+- An `AttachmentTable` in your schema:
+
+  ```ts
+  import { AttachmentTable, Schema } from "@powersync/web"
+
+  const APP_SCHEMA = new Schema({
+    // ...your tables
+    attachments: new AttachmentTable(),
+  })
+  ```
+
+- A local storage adapter (such as `IndexDBFileSystemStorageAdapter` on web) and a remote storage adapter (an implementation of the SDK's `RemoteStorageAdapter`, for example backed by Supabase Storage). Both are generic to all attachment users. See the SDK docs for the available adapters and the remote-adapter contract.
+
+### 1. Create the attachments collection
+
+This is the piece that makes the integration TanStack-aware: a normal PowerSync collection over the attachments table. The queue reads and writes attachment records through it.
+
+```ts
+import { createCollection } from "@tanstack/react-db"
+import { powerSyncCollectionOptions } from "@tanstack/powersync-db-collection"
+
+const attachmentsCollection = createCollection(
+  powerSyncCollectionOptions({
+    database: db,
+    table: APP_SCHEMA.props.attachments,
+  })
+)
+```
+
+### 2. Construct the queue
+
+Pass your collection as `attachmentsCollection` alongside the standard `AttachmentQueue` options. Only `attachmentsCollection` and `watchAttachments` (below) are specific to this package; `db`, `localStorage`, `remoteStorage`, and `errorHandler` are the usual SDK options.
+
+```ts
+import { TanStackDBAttachmentQueue } from "@tanstack/powersync-db-collection"
+
+const attachmentQueue = new TanStackDBAttachmentQueue({
+  db,
+  attachmentsCollection, // TanStack DB collection over your AttachmentTable
+  localStorage, // SDK local storage adapter
+  remoteStorage, // your RemoteStorageAdapter (see SDK docs)
+  watchAttachments, // see step 3
+  errorHandler, // standard AttachmentQueue error handler (see SDK docs)
+})
+```
+
+Start and stop syncing with the standard `attachmentQueue.startSync()` / `attachmentQueue.stopSync()` lifecycle (see SDK docs), typically inside a React effect or provider.
+
+### 3. Tell the queue which attachments exist (`watchAttachments`)
+
+`watchAttachments` reports the set of attachment IDs your data currently references, so the queue knows what to download and what to archive. With TanStack DB you drive it from a live query: emit the initial state, then re-emit the complete set on every change, and clean up on abort.
+
+```ts
+import {
+  createCollection,
+  isNull,
+  liveQueryCollectionOptions,
+  not,
+} from "@tanstack/db"
+import { WatchedAttachmentItem } from "@powersync/web"
+
+const watchAttachments = async (onUpdate, abortSignal) => {
+  // Every row in your data model that references an attachment.
+  const livePhotoIds = createCollection(
+    liveQueryCollectionOptions({
+      query: (q) =>
+        q
+          .from({ document: listsCollection })
+          .where(({ document }) => not(isNull(document.photo_id)))
+          .select(({ document }) => ({ photo_id: document.photo_id })),
+    })
+  )
+
+  const mapper = (item) =>
+    ({
+      id: item.photo_id,
+      fileExtension: "jpg",
+    }) satisfies WatchedAttachmentItem
+
+  // 1. Report the initial set of referenced attachment IDs.
+  const initialState = await livePhotoIds.stateWhenReady()
+  onUpdate(Array.from(initialState.values()).map(mapper))
+
+  // 2. Re-emit the whole set on every change (the queue expects the holistic state).
+  livePhotoIds.subscribeChanges(() => {
+    onUpdate(livePhotoIds.map(mapper))
+  })
+
+  // 3. Clean up when sync stops.
+  abortSignal.addEventListener("abort", () => livePhotoIds.cleanup(), {
+    once: true,
+  })
+}
+```
+
+> A `watchAttachmentsFromQuery(...)` convenience helper that collapses this boilerplate into a single call is planned. Until then, use the pattern above.
+
+### 4. Save an attachment atomically with related data
+
+`save` writes the file, inserts the attachment record into your collection, and runs your `updateHook` mutations in the same transaction. Use the hook to insert or update the row that references the new attachment, so both land together or not at all.
+
+```ts
+await attachmentQueue.save({
+  data, // file bytes (ArrayBuffer / base64, per your local adapter)
+  fileExtension: "jpg",
+  updateHook: async (attachmentRecord) => {
+    // Runs in the same transaction as the attachment insert.
+    listsCollection.insert({
+      id: crypto.randomUUID(),
+      name,
+      created_at: new Date(),
+      owner_id: userID,
+      photo_id: attachmentRecord.id, // associate the row with the attachment
+    })
+  },
+})
+```
+
+### 5. Delete an attachment and detach it from the row
+
+`delete` queues the file for deletion and runs your `updateHook` in the same transaction. Clear the foreign key so the row and the attachment stay consistent.
+
+```ts
+await attachmentQueue.delete({
+  id: photo_id,
+  updateHook: async () => {
+    listsCollection.update(listId, (draft) => {
+      draft.photo_id = null
+    })
+  },
+})
+```
+
+### 6. Display attachments via a live-query join
+
+Join your attachments collection into a live query to read the local URI (the locally cached file path) alongside your domain rows:
+
+```ts
+import { eq } from "@tanstack/db"
+
+const { data } = useLiveQuery((q) =>
+  q
+    .from({ lists: listsCollection })
+    .leftJoin({ attachment: attachmentsCollection }, ({ lists, attachment }) =>
+      eq(lists.photo_id, attachment.id)
+    )
+    .select(({ lists, attachment }) => ({
+      id: lists.id,
+      name: lists.name,
+      photo_id: lists.photo_id,
+      attachment_local_uri: attachment?.local_uri,
+    }))
+)
 ```