feat: [PowerSync] Support Collection Metadata

[stevensJourney]

🎯 Changes

closes #959

Summary

• Add support for tracking collection operation metadata in PowerSync CrudEntry records
• When trackMetadata: true is enabled on a PowerSync table, metadata passed to insert, update, and delete operations is persisted and available during upload processing

Description

This PR enables PowerSync collections to track custom metadata alongside CRUD operations. This is useful for passing additional context about mutations to the backend, such as audit information, operation sources, or custom processing hints.

Key Changes

Metadata Persistence:

• Leverages PowerSync's built-in trackMetadata table option to persist metadata with CRUD operations
• Insert and update operations populate the _metadata column when metadata is provided
• Delete operations with metadata use PowerSync's soft-delete pattern (_deleted = TRUE) to preserve metadata

Validation & Warnings:

• Added metadataIsTracked to PowerSyncCollectionMeta to track table configuration
• Logs a warning if metadata is provided to a collection whose table doesn't have trackMetadata: true

Developer Experience:

• Added documentation section covering enablement, usage in operations, and accessing metadata during upload

Usage

// Enable in schema
const APP_SCHEMA = new Schema({
  documents: new Table(
    { name: column.text, author: column.text },
    { trackMetadata: true }
  ),
})

// Use in operations
await collection.insert(
  { id, name: "doc", author: "Jane" },
  { metadata: { source: "web-app", userId: "user-123" } }
)

Accessing Metadata During Upload:

import { CrudEntry } from "@powersync/web"

class Connector implements PowerSyncBackendConnector {
  // ...

  async uploadData(database: AbstractPowerSyncDatabase) {
    const batch = await database.getCrudBatch()
    if (!batch) return

    for (const entry of batch.crud) {
      console.log("Operation:", entry.op) // PUT, PATCH, DELETE
      console.log("Table:", entry.table)
      console.log("Data:", entry.opData)
      console.log("Metadata:", entry.metadata) // Custom metadata (stringified)

      // Parse metadata if needed
      if (entry.metadata) {
        const meta = JSON.parse(entry.metadata)
        console.log("Source:", meta.source)
        console.log("User ID:", meta.userId)
      }

      // Process the operation with the backend...
    }

    await batch.complete()
  }
}

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

[changeset-bot]

🦋 Changeset detected

Latest commit: f30f95b

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

This PR includes changesets to release 1 package

Name	Type
@tanstack/powersync-db-collection	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

[pkg-pr-new]

More templates

• todos
• tanstack-start-example-basic
• @tanstack/db-example-paced-mutations-demo
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• @tanstack/db-example-solid-todo

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@999

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@999

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@999

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@999

@tanstack/offline-transactions

npm i https://pkg.pr.new/@tanstack/offline-transactions@999

@tanstack/powersync-db-collection

npm i https://pkg.pr.new/@tanstack/powersync-db-collection@999

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@999

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@999

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@999

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@999

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@999

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@999

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@999

commit: f30f95b

[autofix-ci]

Hi! I'm autofix.ci, a bot that automatically fixes trivial issues such as code formatting in pull requests.

I would like to apply some automated changes to this pull request, but it looks like I don't have the necessary permissions to do so. To get this pull request into a mergeable state, please do one of the following two things:

1. Allow edits by maintainers for your pull request, and then re-trigger CI (for example by pushing a new commit).
2. Manually fix the issues identified for your pull request (see the GitHub Actions output for details on what I would like to change).