[POC] PowerSync Integration

[stevensJourney]

🎯 Changes

This PR adds a PowerSync integration for TanStack DB collections. This PR is just a temporary internal PR for discussion. Ideally, a PR would be made upstream after internal discussion.

There are multiple options for integrating PowerSync with TanStack DB collections. The main options are to either:

1. Use a PowerSync SDK client as the data source
2. Connect directly to a PowerSync service sync stream for data operations

The work here investigates and implements 1, while 2 can be implemented in a different PR.

The PowerSync SDK is used for both syncing data to local SQLite tables as well as perform uploads via the PowerSyncBackendConnector.

TanStack DB collections are tied to the local SQLite tables with the help of collection builders. These collection builders link the TanStack collection state to the SQLite table via Trigger based diff tracking. Mutations made on TanStack DB collections are persisted to SQLite via PowerSyncTransactor, once persisted the upload queue ensures changes are uploaded to a backend.

flowchart TB
    subgraph UI[UI Layer]
        UI_Component[UI Components]
    end

    subgraph TanStack[TanStack DB Layer]
        TS_Cache[In-Memory Cache]
        TS_Collections[TanStack Collections]
    end

    subgraph PowerSync[PowerSync Layer]
        PS_SQLite[Local SQLite DB]
        PS_Client[PowerSync Client]
    end

    subgraph Backend[Backend Infrastructure]
        Backend_App[Application Backend]
        PS_Service[PowerSync Service]
    end

    UI_Component -->|Mutations| TS_Collections
    TS_Cache -->|Updates| UI_Component

    TS_Collections -->|Persist| PS_SQLite
    PS_SQLite -->|Watch| TS_Cache

    PS_Client -->|Sync| PS_SQLite
    PS_SQLite -->|Changes| PS_Client
    PS_Client -->|Changes| Backend_App
    Backend_App -->|Apply| PS_Service
    PS_Service -->|Sync| PS_Client

    style UI fill:#f9f,stroke:#333,stroke-width:2px
    style TanStack fill:#bbf,stroke:#333,stroke-width:2px
    style PowerSync fill:#bfb,stroke:#333,stroke-width:2px
    style Backend fill:#fdb,stroke:#333,stroke-width:2px

Loading

Detailed examples are in the unit tests. The main flow is to:

Create a PowerSync SDK Client

const APP_SCHEMA = new Schema({
  users: new Table({
    name: column.text
  }),
  documents: new Table({
    name: column.text
  })
});

type Document = (typeof APP_SCHEMA)[`types`][`documents`];
type User = (typeof APP_SCHEMA)[`types`][`users`];

const db = new PowerSyncDatabase({
  database: {
    dbFilename: `test.sqlite`
  },
  schema: APP_SCHEMA
});

db.connect(connector);

Define TanStack DB collections using the database

const documentsCollection = createCollection(
  powerSyncCollectionOptions({
    database: db,
    table: APP_SCHEMA.props.documents
  })
);

Use the TanStack DB collections as one would any other collection

// Create a new item synchronously
const id = randomUUID();
const tx = documentsCollection.insert({
  id,
  name: `new`
});

// Synchronous data is available immediately
const newDoc = collection.get(id);

collection.update(id, (d) => (d.name = `updatedNew`));

// More advanced transactions can do this
const addTx = createTransaction({
  autoCommit: false,
  mutationFn: async ({ transaction }) => {
    await new PowerSyncTransactor({ database: db }).applyTransaction(transaction);
  }
});

addTx.mutate(() => {
  for (let i = 0; i < 5; i++) {
    documentsCollection.insert({ id: randomUUID(), name: `tx-${i}` });
    usersCollection.insert({ id: randomUUID(), name: `user` });
  }
});

✅ Checklist

PowerSync TODOs

• Test Schema support

• Add documentation

• The Node.js SDK requires install scripts which don't run automatically - breaks tests

• I have followed the steps in the Contributing guide (Seems like a dead link, the repo also does not seem to have a CONTRIBUTING.md file)

• I have tested this code locally with pnpm test:pr (There does not seem to be a script for this)

🚀 Release Impact

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

[stevensJourney]

This might need to match the other packages in this repo's license (MIT)