PowerSync JS Demos

When you change the parameters of a useSuspenseQuery (e.g., changing a filter or a limit), the hook restarts and enters a suspending state, which triggers the <Suspense> fallback.

To keep displaying the current (stale) data while the new query is fetching, you should wrap the parameter update in React's startTransition or use the useDeferredValue hook. This prevents the UI from jumping back to the loading state.

// Example using startTransition to prevent fallback
import { ErrorBoundary } from 'react-error-boundary';
import React, { Suspense } from 'react';
import { useSuspenseQuery } from '@powersync/react';

const TodoListContent = () => {
  const [query, setQuery] = React.useState('SELECT * FROM lists');
  const { data: todoLists } = useSuspenseQuery(query);

  return (
    <div
      >
      <button
        onClick={() => {
          React.startTransition(() => setQuery('SELECT * from lists limit 1'));
        }}>
        Update
      </button>
      <ul
        >{todoLists.map((list) => (
          <li key={list.id}>{list.name}</li
        ))}
      </ul
    </div
  );
};

export const TodoListDisplaySuspense = () => {
  return (
  <ErrorBoundary fallback={<div>Something went wrong</div>}>
    <Suspense fallback={<div>Loading todo lists...</div>}>
      <TodoListContent />
    </Suspense>
  </ErrorBoundary>
  );
};

The demo implements a pattern to allow users to use the app without an account, then seamlessly sync their data once they register.

Core Concept: Local-only Tables

The app uses local-only tables to persist data before registration. These tables do not log updates in the upload queue, preventing unnecessary database growth.

The Recommended Implementation Pattern

To avoid changing application queries when a user signs in, the app uses the viewName property to override table names.

1. Local-only State: Local tables (e.g., local_lists) have their viewName set to the standard table name (e.g., lists). The app queries SELECT * FROM lists, which points to the local table. The actual synced tables are assigned an inactive_synced_ view name so they are ignored.
2. Transition: When the user signs in, updateSchema is called to change the viewName of the synced tables back to the standard names (e.g., lists).
3. Data Migration: Data is copied from the local-only tables to the synced tables, and the local-only data is deleted to save space. The synced tables then automatically begin uploading data to the backend.

Limitations

• updateSchema cannot be called inside a transaction. It is recommended to perform schema updates when the database is not connected.

By default, useQuery triggers a new data array reference whenever any change is detected in the underlying tables, even if the specific query result hasn't changed. This can cause frequent re-renders.

Incremental Queries solve this by performing in-memory comparisons. When configured with a rowComparator, the data array reference remains the same if the result set is unchanged. Additionally, individual row object references are preserved for unchanged rows.

To enable this, provide a rowComparator object in the options:

• keyBy: A function to extract a unique key from an item.
• compareBy: A function to determine if an item has changed (e.g., using JSON.stringify).

const { data, isLoading, isFetching } = useQuery(
  `SELECT * FROM cats WHERE breed = 'tabby'`, 
  [], 
  {
    rowComparator: {
      keyBy: (item) => item.id,
      compareBy: (item) => JSON.stringify(item)
    }
  }
)

The watchAttachments callback is a required configuration for AttachmentQueue. It tells the queue which attachments it is responsible for (downloading, uploading, or archiving) by providing a list of WatchedAttachmentItem objects.

Important: Each item in the array must provide either fileExtension OR filename, but not both.

WatchedAttachmentItem Types:

• { id: string; fileExtension: string; metaData?: string; mediaType?: string; }
• { id: string; filename: string; metaData?: string; mediaType?: string; }

Example Implementation: Use a PowerSync db.watch() query to detect changes in your application tables (e.g., a users table containing a photo_id) and map those rows to WatchedAttachmentItem objects.

watchAttachments: (onUpdate) => {
  // Watch photo references in users table
  db.watch(
    'SELECT photo_id, metadata FROM users WHERE photo_id IS NOT NULL',
    [],
    {
      onResult: async (result) => {
        const attachments = result.rows?._array.map(row => ({
          id: row.photo_id,
          fileExtension: 'jpg',
          metaData: row.metadata
        })) ?? [];
        await onUpdate(attachments);
      }
    }
  );
}