RxDBDotNet

https://github.com/ziptility/rxdbdotnet
Admin
A powerful .NET library that implements the RxDB replication protocol for real-time data...
Tokens:14,628
Snippets:188
Trust Score:3.6
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Update README with Setup and Usage Guidelines

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Enhances the main README.md file with updated setup instructions, including cloning, dependency installation, environment configuration, and starting the development server. It also includes sections for usage guidelines and troubleshooting.

```markdown
# RxDBDotNet Example Client App

## Setup Instructions

1. Clone the repository
2. Install dependencies: `npm install`
3. Configure environment variables (see `.env.example`)
4. Start the development server: `npm run dev`

## Usage Guidelines

- Offline-First Operations: ...
- Synchronization: ...
- Conflict Resolution: ...
- Performance Optimization: ...

## Troubleshooting

- Sync Issues: ...
- Performance Problems: ...
```

--------------------------------

### Install Node.js Dependencies

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Install all necessary Node.js dependencies for the example client application.

```bash
npm install
```

--------------------------------

### Navigate to Example Client Directory

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Change the current directory to the RxDBDotNet example client application.

```bash
cd RxDBDotNet/example/livedocs-client
```

--------------------------------

### Build and Start Application

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Combines the `build` and `start` scripts to build the application for production and then run it. Useful for a quick test of the production build.

```bash
npm run run
```

--------------------------------

### Install RxDBDotNet Package

Source: https://github.com/ziptility/rxdbdotnet/blob/main/README.md

Install the RxDBDotNet package using the .NET CLI.

```bash
dotnet add package RxDBDotNet
```

--------------------------------

### Start Development Server

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Starts the Next.js development server on port 3000. This script is used for local development and debugging.

```bash
npm run dev
```

--------------------------------

### Run Backend API (Development)

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Starts the backend API in development mode without launching the frontend. Navigate to the specified directory before running.

```bash
dotnet run --launch-profile api-only
```

--------------------------------

### Run Full Stack (Production)

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Starts the full stack application, including the backend API and production build of the frontend. Navigate to the specified directory before running.

```bash
dotnet run --launch-profile full-stack
```

--------------------------------

### Document Local-First Patterns

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Introduces a new markdown file, `docs/local-first-patterns.md`, to document implemented local-first patterns within the RxDBDotNet Example Client App, including code examples.

```markdown
# Local-First Patterns in RxDBDotNet Example Client App


```

--------------------------------

### Multi-Collection Replication Setup

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Sets up replication for multiple RxDB collections including workspaces, users, and livedocs using provided JWT access token.

```typescript
export const setupReplication = (db: LiveDocsDatabase, jwtAccessToken: string): LiveDocsReplicationStates => {
  const token = jwtAccessToken || API_CONFIG.DEFAULT_JWT_TOKEN;

  try {
    console.log('Setting up replication with token:', token);
    const replicationStates: LiveDocsReplicationStates = {
      workspaces: replicateWorkspaces(token, db.workspace),
      users: replicateUsers(token, db.user),
      livedocs: replicateLiveDocs(token, db.livedoc),
    };
    console.log('Replication setup completed');
    return replicationStates;
  } catch (error) {
    handleError(error, 'setupReplication', { jwtAccessToken });
    throw error;
  }
};
```

--------------------------------

### Start Production Application

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Runs the built production version of the Next.js application on port 3000. This is typically used after running `npm run build`.

```bash
npm run start
```

--------------------------------

### Setup Basic Logging for RxDB Operations

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Configures basic logging for RxDB database and collection events. This is useful for monitoring database activity and debugging.

```typescript
import { RxDatabase } from 'rxdb';

export const setupLogging = (db: RxDatabase) => {
  db.$.subscribe((event) => {
    console.log('Database event:', event);
  });

  Object.values(db.collections).forEach((collection) => {
    collection.$.subscribe((event) => {
      console.log(`Collection ${collection.name} event:`, event);
    });
  });
};
```

--------------------------------

### GraphQL Replication Setup

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/docs/local-first-patterns.md

Configure RxDB to replicate data with a GraphQL endpoint. Ensure 'live' is true for continuous synchronization and configure retry mechanisms for network resilience.

```typescript
import { replicateGraphQL } from 'rxdb/plugins/replication-graphql';

const replicationState = replicateGraphQL({
  collection: collections.documents,
  url: 'https://api.example.com/graphql',
  pull: {
    queryBuilder: pullQueryBuilder,
    modifier: (doc) => doc,
  },
  push: {
    queryBuilder: pushQueryBuilder,
    modifier: (doc) => doc,
  },
  live: true,
  retry: {
    autoReconnect: true,
    maxRetries: Infinity,
    retryDelay: (attempt) => Math.min(attempt * 1000, 30000), // Exponential backoff with max 30s delay
  },
});

// Optionally observe replication state
replicationState.error$.subscribe((error) => {
  console.error('Replication error:', error);
});

replicationState.active$.subscribe((active) => {
  console.log('Replication active:', active);
});
```

--------------------------------

### Open Project in VS Code

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Opens the livedocs-client project directory in Visual Studio Code. Ensure VS Code is installed and in your PATH.

```bash
code .
```

--------------------------------

### Filtered Replication Setup

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Configures GraphQL replication with custom filters, topic subscriptions, and response handling for selective data synchronization.

```typescript
export const replicateWorkspaces = (
  token: string,
  collection: RxCollection<Workspace>,
  filter?: WorkspaceFilterInput,
  topics: string[] = [],
  batchSize = 100
): LiveDocsReplicationState<Workspace> => {
  const replicationState = replicateGraphQL({
    collection,
    url: {
      http: API_CONFIG.GRAPHQL_ENDPOINT,
      ws: API_CONFIG.WS_ENDPOINT,
    },
    pull: {
      queryBuilder: pullQueryBuilder(filter),
      streamQueryBuilder: pullStreamBuilder(topics),
      batchSize,
      includeWsHeaders: true,
    },
    push: {
      queryBuilder: pushQueryBuilder,
      batchSize,
      responseModifier: (response: PushWorkspacePayload): ReplicationPushHandlerResult<Workspace> => {
        if (response.errors) {
          response.errors.forEach((error) => handleError(error, 'Workspace replication push'));
        }
        return response.workspace ?? [];
      },
    },
    live: true,
    deletedField: 'isDeleted',
    headers: {
      Authorization: `Bearer ${token}`,
    },
    replicationIdentifier: 'workspace-replication',
    autoStart: true,
  });

  initializeLoggingAndErrorHandlers(replicationState);

  return replicationState;
};
```

--------------------------------

### Configure OIDC Authentication Scheme for Subscriptions

Source: https://github.com/ziptility/rxdbdotnet/blob/main/README.md

Integrate OpenID Connect (OIDC) for subscription authentication. This setup automatically handles dynamic key retrieval and rotation from the specified authority.

```csharp
builder.Services
    .AddAuthentication()
    .AddJwtBearer("OidcScheme", options =>
    {
        options.Authority = "https://your-identity-provider.com";
        options.Audience = "your-api";
        options.RequireHttpsMetadata = true;
    });

builder.Services
    .AddGraphQLServer()
    .AddMutationConventions()
    .AddReplication(options => 
    {
        options.Security
            .TryAddSubscriptionAuthenticationScheme("OidcScheme");
    });
```

--------------------------------

### Build Granular Pull Queries for Workspace Replication

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Implement more granular pull queries to reduce data transfer during synchronization. This example shows a selective query for workspace documents, including only necessary fields.

```typescript
const pullQueryBuilder = (variables: WorkspaceFilterInput): RxGraphQLReplicationPullQueryBuilder<Checkpoint> => {
  return (checkpoint, limit) => ({
    query: `
      query PullWorkspace($checkpoint: WorkspaceInputCheckpoint, $limit: Int!, $where: WorkspaceFilterInput) {
        pullWorkspace(checkpoint: $checkpoint, limit: $limit, where: $where) {
          documents {
            id
            name
            updatedAt
            isDeleted
            # Add any other necessary fields, but be selective to reduce data transfer
          }
          checkpoint {
            lastDocumentId
            updatedAt
          }
        }
      }
    `,
    variables: { checkpoint, limit, where: variables },
  });
};

// Implement similar enhancements for push operations and other replication files
```

--------------------------------

### Efficient RxDB Querying with Limits and Sorting

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/docs/local-first-patterns.md

Perform efficient queries using RxDB's find method with selectors, sorting, and limit options. This example retrieves the 50 most recent documents from the last 7 days.

```typescript
const recentDocuments = await collection
  .find({
    selector: {
      createdAt: {
        $gt: Date.now() - 7 * 24 * 60 * 60 * 1000, // Last 7 days
      },
    },
    sort: [{ createdAt: 'desc' }],
    limit: 50,
  })
  .exec();
```

--------------------------------

### Default JWT Bearer Authentication for Subscriptions

Source: https://github.com/ziptility/rxdbdotnet/blob/main/README.md

Configure the default JWT Bearer authentication scheme for GraphQL subscriptions. This is the minimal setup required for standard JWT authentication.

```csharp
builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = // ... your token validation parameters
    });

builder.Services
    .AddGraphQLServer()
    .AddMutationConventions()
    .AddReplication() // Uses default Bearer scheme
```

--------------------------------

### Implement Custom Conflict Handler in TypeScript

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Define a custom conflict handler for RxDB collections to manage synchronization conflicts. This example shows how to prioritize the most recently updated document.

```typescript
const customWorkspaceConflictHandler: RxConflictHandler<Workspace> = async (
  i: RxConflictHandlerInput<Workspace>
): Promise<RxConflictHandlerOutput<Workspace>> => {
  if (i.newDocumentState.updatedAt > i.realMasterState.updatedAt) {
    return { isEqual: false, documentData: i.newDocumentState };
  }
  return { isEqual: false, documentData: i.realMasterState };
};

const collections = await db.addCollections({
  workspace: {
    schema: workspaceSchema,
    conflictHandler: customWorkspaceConflictHandler,
  },
  // Add similar conflict handlers for other collections
});
```

--------------------------------

### Database Initialization with Replication

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Initializes the RxDB database, adds collections, sets up replication, and configures logging.

```typescript
const initializeDatabase = async (): Promise<LiveDocsDatabase> => {
  try {
    const db = await createRxDatabase<LiveDocsCollections>({
      name: 'livedocsdb',
      storage: getRxStorageDexie(),
      multiInstance: false,
      ignoreDuplicate: false,
      eventReduce: true,
    });

    console.log('Database created successfully');

    await db.addCollections(createCollections());
    console.log('Collections added successfully');

    const replicationStates = setupReplication(db, API_CONFIG.DEFAULT_JWT_TOKEN);
    console.log('Replication set up successfully');

    setupReplicationLogging(replicationStates);

    return Object.assign(db, { replicationStates }) as LiveDocsDatabase;
  } catch (error) {
    handleError(error, 'initializeDatabase');
    throw error;
  }
};
```

--------------------------------

### Create Live Document with Topics

Source: https://github.com/ziptility/rxdbdotnet/blob/main/README.md

Specify topics when creating or updating a document to control real-time updates. Ensure the document includes a 'Topics' property with a list of relevant topic strings.

```csharp
var liveDoc = new LiveDoc
{
    Id = Guid.NewGuid(),
    Content = "New document content",
    UpdatedAt = DateTimeOffset.UtcNow,
    IsDeleted = false,
    WorkspaceId = workspaceId,
    Topics = new List<string> { $"workspace-{workspaceId}" }
};

await documentService.CreateAsync(liveDoc, CancellationToken.None);
```

--------------------------------

### Configure RxDBDotNet Services in Program.cs

Source: https://github.com/ziptility/rxdbdotnet/blob/main/README.md

Register your document service and configure the GraphQL server with RxDBDotNet replication services. Ensure mutation conventions and in-memory subscriptions are enabled.

```csharp
// Add your document service to the DI container
builder.Services
    .AddSingleton<IReplicatedDocumentService<Workspace>, WorkspaceService>();

// Configure the Hot Chocolate GraphQL server
builder.Services
    .AddGraphQLServer()
     // Mutation conventions must be enabled for replication to work
    .AddMutationConventions()
    // Enable RxDBDotNet replication services
    .AddReplication()
    // Register the document to be replicated
    .AddReplicatedDocument<Workspace>()
    .AddInMemorySubscriptions();

var app = builder.Build();

app.UseWebSockets();
app.MapGraphQL();

app.Run();
```

--------------------------------

### Build Application

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Builds the Next.js application for production deployment. This command optimizes the application for performance.

```bash
npm run build
```

--------------------------------

### Implement Virtualization for Large Lists

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Uses `react-window` to implement list virtualization for components like WorkspaceList, improving performance by rendering only visible items. Similar implementations are suggested for UserList and LiveDocList.

```typescript
import { FixedSizeList as List } from 'react-window';

const WorkspaceList: React.FC<WorkspaceListProps> = ({ workspaces, ...props }) => {
  const Row = ({ index, style }) => {
    const workspace = workspaces[index];
    return (
      <div style={style}>
        {/* Render workspace item */}
      </div>
    );
  };

  return (
    <List
      height={400}
      itemCount={workspaces.length}
      itemSize={50}
      width="100%"
    >
      {Row}
    </List>
  );
};

// Implement similar virtualization for UserList and LiveDocList
```

--------------------------------

### Format Code

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Formats all supported files in the project using Prettier. This ensures consistent code style across the project.

```bash
npm run format
```

--------------------------------

### Clone RxDBDotNet Repository

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Clone the RxDBDotNet repository to your local machine.

```bash
git clone https://github.com/Ziptility/RxDBDotNet.git
```

--------------------------------

### Local-First Data Flow with RxDB

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/docs/local-first-patterns.md

Perform all read and write operations directly on the local RxDB instance. Use RxDB's built-in replication for synchronization.

```typescript
import {
  createRxDatabase
} from 'rxdb';
import { getRxStorageDexie } from 'rxdb/plugins/storage-dexie';

const db = await createRxDatabase({
  name: 'exampledb',
  storage: getRxStorageDexie(),
});

const collections = await db.addCollections({
  documents: {
    schema: mySchema,
  },
});

// All operations are performed on the local database
async function createDocument(data) {
  await collections.documents.insert(data);
}

async function readDocument(id) {
  return await collections.documents.findOne(id).exec();
}

async function updateDocument(id, data) {
  const doc = await collections.documents.findOne(id).exec();
  await doc.update(data);
}
```

--------------------------------

### Configure Document Security Options

Source: https://github.com/ziptility/rxdbdotnet/blob/main/README.md

Apply security policies to specific replicated documents using the security options during GraphQL server configuration. This restricts read and write access based on defined policies.

```csharp
builder.Services
    .AddGraphQLServer()
    .AddReplicatedDocument<Workspace>(options =>
    {
        options.Security = new SecurityOptions()
            .RequirePolicyToRead("CanReadWorkspace")
            .RequirePolicyToWrite("IsWorkspaceAdmin");
    });
```

--------------------------------

### Implement Document Service

Source: https://github.com/ziptility/rxdbdotnet/blob/main/README.md

Create a service that implements IReplicatedDocumentService for your specific document type.

```csharp
public class WorkspaceService : IReplicatedDocumentService<Workspace>
{
    // Implement the required methods
    // ...
}
```

--------------------------------

### Enhance Login Functionality with Token Refresh Simulation

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Improves the login process by simulating token refresh using `setInterval`. This is part of enhancing the 'Login As' functionality to better mimic real-world scenarios.

```typescript
const LoginPage: React.FC = () => {
  // ... existing code ...

  const handleLogin = async (userId: string, workspaceId: string) => {
    try {
      await login(userId, workspaceId);
      // Simulate token refresh
      setInterval(
        () => {
          refreshToken();
        },
        60 * 60 * 1000
      ); // Refresh every hour
    } catch (error) {
      handleError(error, 'Login');
    }
  };

  // ... render login form ...
};
```

--------------------------------

### Configure Replication with Retry Logic and Pause/Resume

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Enhance synchronization by implementing robust error handling, retry logic, and support for pausing and resuming synchronization based on network conditions. Configure replication with specific retry intervals and batch sizes.

```typescript
export const setupReplication = (db: LiveDocsDatabase, jwtAccessToken: string) => {
  // ... existing code ...

  const replicationStates = {
    workspaces: createWorkspaceReplicator(token, db.workspace, {
      retryInterval: 5000,
      maxRetries: 3,
      batchSize: 50,
    }),
    // ... similar enhancements for other replicators ...
  };

  // Implement pause/resume logic
  window.addEventListener('online', () => resumeAllReplications(replicationStates));
  window.addEventListener('offline', () => pauseAllReplications(replicationStates));

  return replicationStates;
};
```

--------------------------------

### Build Pull Stream Query Builder for Real-time Updates

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Constructs a pull stream query builder for RxGraphQLReplication. This enables clients to subscribe to specific topics and receive real-time updates efficiently by filtering at the source.

```typescript
const pullStreamBuilder = (topics: string[]): RxGraphQLReplicationPullStreamQueryBuilder => {
  return (headers: { [k: string]: string }) => {
    const query = `
      subscription StreamWorkspace($headers: WorkspaceInputHeaders, $topics: [String!]) {
        streamWorkspace(headers: $headers, topics: $topics) {
          documents {
            id
            name
            topics
            updatedAt
            isDeleted
          }
          checkpoint {
            lastDocumentId
            updatedAt
          }
        }
      }
    `;

    return {
      query,
      variables: {
        headers,
        topics,
      },
    };
  };
};
```

--------------------------------

### Subscribe to Live Documents by Topic

Source: https://github.com/ziptility/rxdbdotnet/blob/main/README.md

Subscribe to real-time updates for documents filtered by specific topics. The GraphQL query specifies the topics to listen to and the fields to retrieve.

```graphql
subscription StreamLiveDocs {
  streamLiveDoc(topics: ["workspace-123e4567-e89b-12d3-a456-426614174000"]) {
    documents {
      id
      content
      updatedAt
      isDeleted
      workspaceId
    }
    checkpoint {
      updatedAt
      lastDocumentId
    }
  }
}
```

--------------------------------

### Build Push Mutation for Workspace Changes

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Creates a custom push query builder for RxGraphQLReplication. This function generates a GraphQL mutation to send local changes to the server, handling potential authentication or authorization errors.

```typescript
const pushQueryBuilder: RxGraphQLReplicationPushQueryBuilder = (
  pushRows: RxReplicationWriteToMasterRow<Workspace>[]
) => {
  const query = `
    mutation PushWorkspace($input: PushWorkspaceInput!) {
      pushWorkspace(input: $input) {
        workspace {
          id
          name
          topics
          updatedAt
          isDeleted
        }
        errors {
          ... on AuthenticationError {
            message
          }
          ... on UnauthorizedAccessError {
            message
          }
        }
      }
    }
  `;

  return {
    query,
    operationName: 'PushWorkspace',
    variables: {
      input: {
        workspacePushRow: pushRows,
      },
    },
  };
};
```

--------------------------------

### Implement Sync Recovery Logic

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/docs/local-first-patterns.md

Use this hook to manage synchronization state and trigger re-syncing when the network becomes available. It handles UI updates and error reporting.

```typescript
function useSyncRecovery(replicationState) {
  const [isSyncing, setIsSyncing] = useState(false);
  const isOnline = useNetworkStatus();

  useEffect(() => {
    if (isOnline) {
      setIsSyncing(true);
      replicationState.reSync().then(() => {
        setIsSyncing(false);
        showToast('All changes synced');
      }).catch(error => {
        console.error('Sync failed:', error);
        showToast('Sync failed, will retry later');
      });
    }
  }, [isOnline, replicationState]);

  return isSyncing;
}

function SyncRecoveryIndicator({ replicationState }) {
  const isSyncing = useSyncRecovery(replicationState);

  if (!isSyncing) return null;

  return (
    <LinearProgress variant="indeterminate" />
  );
}
```

--------------------------------

### Clean Build Artifacts

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Removes the `.next` and `out` directories, which contain build artifacts. This is useful for ensuring a clean build.

```bash
npm run clean
```

--------------------------------

### Implement Optimistic Updates in Client

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Handles optimistic updates for a more responsive user experience. It first applies a temporary update locally and then synchronizes with the server, reverting or updating based on the server's response.

```typescript
const handleCreate = async (data) => {
  // Optimistic update
  setItems((prev) => [...prev, { ...data, id: 'temp-id' }]);

  try {
    const result = await createItem(data);
    // Update with actual data from server
    setItems((prev) => prev.map((item) => (item.id === 'temp-id' ? result : item)));
  } catch (error) {
    // Revert optimistic update
    setItems((prev) => prev.filter((item) => item.id !== 'temp-id'));
    handleError(error, 'Create Item');
  }
};
```

--------------------------------

### Define RxDB Schema with Indexes

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/docs/local-first-patterns.md

Define document schema with primary keys and indexes to optimize local queries. Indexes like 'createdAt' improve performance for sorted or filtered data.

```typescript
const documentsSchema = {
  version: 0,
  type: 'object',
  properties: {
    id: {
      type: 'string',
      primary: true,
    },
    title: {
      type: 'string',
    },
    createdAt: {
      type: 'number',
    },
  },
  indexes: ['createdAt'],
};
```

--------------------------------

### Implement Optimistic UI Updates in React

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Demonstrates how to implement optimistic UI updates in a React component for a workspace submission. It involves temporarily adding a new item and then updating or reverting it based on the server response.

```typescript
const WorkspacesPageContent: React.FC = () => {
  // ... existing code ...

  const handleSubmit = useCallback(
    async (workspaceData) => {
      // Optimistic update
      setWorkspaces((prev) => [...prev, { ...workspaceData, id: 'temp-id' }]);

      try {
        const result = await upsertDocument(workspaceData);
        // Update with actual data from server
        setWorkspaces((prev) => prev.map((w) => (w.id === 'temp-id' ? result : w)));
      } catch (error) {
        // Revert optimistic update
        setWorkspaces((prev) => prev.filter((w) => w.id !== 'temp-id'));
        // Handle error
      }
    },
    [upsertDocument]
  );

  // Implement similar optimistic updates for update and delete operations
};
```

--------------------------------

### Instant UI Updates with RxDB Hooks

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/docs/local-first-patterns.md

Update the UI automatically when local data changes by subscribing to RxDB observables. This pattern ensures immediate user feedback.

```typescript
import { useRxCollection } from 'rxdb-hooks';

function DocumentEditor({ documentId }) {
  const collection = useRxCollection('documents');
  const [doc, setDoc] = useState(null);

  useEffect(() => {
    const subscription = collection.findOne(documentId).$.subscribe(setDoc);
    return () => subscription.unsubscribe();
  }, [documentId, collection]);

  const handleUpdate = async (newData) => {
    try {
      await collection.findOne(documentId).update(newData);
      // UI updates automatically due to subscription
    } catch (error) {
      console.error('Update failed:', error);
    }
  };

  // Render document editor
}
```

--------------------------------

### Implement Virtual Scrolling with React Window

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/docs/local-first-patterns.md

Use 'react-window' to implement virtual scrolling for large lists of documents, improving performance by only rendering visible items. Requires a 'DocumentItem' component.

```typescript
import { FixedSizeList } from 'react-window';

function DocumentList({ documents }) {
  const Row = ({ index, style }) => (
    <div style={style}>
      <DocumentItem document={documents[index]} />
    </div>
  );

  return (
    <FixedSizeList
      height={400}
      itemCount={documents.length}
      itemSize={50}
      width="100%"
    >
      {Row}
    </FixedSizeList>
  );
}
```

--------------------------------

### Configure Multiple Custom JWT Bearer Schemes

Source: https://github.com/ziptility/rxdbdotnet/blob/main/README.md

Set up multiple JWT Bearer authentication schemes with distinct audiences and validation parameters. RxDBDotNet will attempt to validate tokens against these schemes in order.

```csharp
// Configure multiple JWT Bearer schemes
builder.Services
    .AddAuthentication()
    .AddJwtBearer("Bearer", options => 
    {
        options.Audience = "DefaultAudience";
        options.TokenValidationParameters = // ... default scheme parameters
    })
    .AddJwtBearer("CustomScheme", options =>
    {
        options.Audience = "CustomAudience";
        options.TokenValidationParameters = // ... custom scheme parameters
    });

// Configure RxDBDotNet to use both schemes
builder.Services
    .AddGraphQLServer()
    .AddMutationConventions()
    .AddReplication(options => 
    {
        options.Security
            .TryAddSubscriptionAuthenticationScheme("CustomScheme");
        // The default "Bearer" scheme is already included
    });
```

--------------------------------

### Local-Aware UI Sync Status Indicator

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/docs/local-first-patterns.md

Create a UI component that displays the application's synchronization status and online/offline state using RxDB's replication state and browser events.

```typescript
function SyncStatusIndicator() {
  const [syncStatus, setSyncStatus] = useState('idle');
  const [isOnline, setIsOnline] = useState(navigator.onLine);

  useEffect(() => {
    const subscription = replicationState.active$.subscribe(
      isActive => setSyncStatus(isActive ? 'syncing' : 'idle')
    );

    const handleOnline = () => setIsOnline(true);
    const handleOffline = () => setIsOnline(false);
    window.addEventListener('online', handleOnline);
    window.addEventListener('offline', handleOffline);

    return () => {
      subscription.unsubscribe();
      window.removeEventListener('online', handleOnline);
      window.removeEventListener('offline', handleOffline);
    };
  }, []);

  return (
    <div>
      <Chip
        icon={isOnline ? <SyncIcon /> : <CloudOffIcon />}
        label={isOnline ? (syncStatus === 'syncing' ? 'Syncing...' : 'Synced') : 'Offline'}
        color={isOnline ? 'primary' : 'default'}
        size="small"
      />
    </div>
  );
}
```

--------------------------------

### Optimistic UI Update with RxDB

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/docs/local-first-patterns.md

Implement optimistic UI updates by subscribing to RxDB's find() observable. The UI automatically re-renders when local data changes, providing a responsive user experience.

```typescript
function DocumentList() {
  const collection = useRxCollection('documents');
  const [documents, setDocuments] = useState([]);

  useEffect(() => {
    const subscription = collection.find().$.subscribe(setDocuments);
    return () => subscription.unsubscribe();
  }, [collection]);

  // Render document list
  // UI updates automatically when documents change
}
```

--------------------------------

### Implement Optimistic Updates and Offline Error Handling

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Optimize offline support by implementing optimistic updates for improved perceived performance and adding error handling for offline scenarios. A local-first querying strategy should also be implemented.

```typescript
const useDocuments = <T extends Document>(collectionName: keyof LiveDocsDatabase) => {
  // ... existing code ...

  const upsertDocument = async (doc: T) => {
    try {
      // Optimistic update
      setDocuments((prevDocs) => [...prevDocs.filter((d) => d.id !== doc.id), doc]);
      await collection.upsert(doc);
    } catch (error) {
      // Revert optimistic update if failed
      setDocuments((prevDocs) => prevDocs.filter((d) => d.id !== doc.id));
      // Handle offline scenario
      if (!navigator.onLine) {
        // Queue operation for later or notify user
      }
    }
  };

  // ... implement similar optimistic updates for other operations ...
};
```

--------------------------------

### Implement Token Management and Offline Authentication

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Enhances token management and offline authentication support within the AuthProvider context. It includes logic for refreshing tokens, updating replication tokens, and storing/retrieving authentication data from local storage.

```typescript
const AuthProvider: React.FC = ({ children }) => {
  // ... existing code ...

  const refreshToken = useCallback(async () => {
    // Implement token refresh logic
    const newToken = await fetchNewToken();
    setJwtAccessToken(newToken);
    await updateReplicationToken(newToken);
  }, []);

  const login = useCallback(async (userId: string, workspaceId: string) => {
    // ... existing login logic ...

    // Store authentication data for offline access
    localStorage.setItem('auth', JSON.stringify({ userId, workspaceId, token }));
  }, []);

  useEffect(() => {
    // Check for stored authentication data on init
    const storedAuth = localStorage.getItem('auth');
    if (storedAuth) {
      const { userId, workspaceId, token } = JSON.parse(storedAuth);
      login(userId, workspaceId);
    }
  }, []);

  // ... render provider ...
};
```

--------------------------------

### Implement Database Indexing for Performance

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Defines schema with indexing for collections to optimize query performance in the database. This is crucial for efficient data retrieval.

```typescript
const workspaceSchema = {
  // ... existing schema ...
  indexes: ['name', 'updatedAt'],
};

const userSchema = {
  // ... existing schema ...
  indexes: ['email', 'role', 'workspaceId', 'updatedAt'],
};

const liveDocSchema = {
  // ... existing schema ...
  indexes: ['ownerId', 'workspaceId', 'updatedAt'],
};
```

--------------------------------

### Define Authorization Policies

Source: https://github.com/ziptility/rxdbdotnet/blob/main/README.md

Define custom authorization policies for controlling access to replicated documents. These policies can be based on claims.

```csharp
builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("IsWorkspaceAdmin", policy =>
        policy.RequireClaim("WorkspaceRole", "Admin"));
    
    options.AddPolicy("CanReadWorkspace", policy =>
        policy.RequireClaim("WorkspaceRole", "Admin", "Reader"));
});
```

--------------------------------

### Offline-Aware Button with Operation Queuing

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/docs/local-first-patterns.md

Create a button component that handles offline states by queuing operations when the network is unavailable. Provides user feedback for queued actions. Requires 'queueOfflineOperation' and 'showToast' functions.

```typescript
function OfflineAwareButton({ onClick, children }) {
  const [isOnline, setIsOnline] = useState(navigator.onLine);

  useEffect(() => {
    const handleOnline = () => setIsOnline(true);
    const handleOffline = () => setIsOnline(false);
    window.addEventListener('online', handleOnline);
    window.addEventListener('offline', handleOffline);
    return () => {
      window.removeEventListener('online', handleOnline);
      window.removeEventListener('offline', handleOffline);
    };
  }, []);

  const handleClick = async () => {
    try {
      await onClick();
    } catch (error) {
      if (!isOnline) {
        // Queue the operation for later
        await queueOfflineOperation(onClick);
        // Provide feedback to the user
        showToast('Action will be performed when online');
      } else {
        // Handle other types of errors
        console.error('Operation failed:', error);
      }
    }
  };

  return (
    <Button onClick={handleClick} disabled={!isOnline}>
      {children}
      {!isOnline && <OfflineIcon fontSize="small" />}
    </Button>
  );
}
```

--------------------------------

### Implement IReplicatedDocument Interface

Source: https://github.com/ziptility/rxdbdotnet/blob/main/README.md

Define your document type by implementing the IReplicatedDocument interface. Ensure 'Id', 'Name', 'UpdatedAt', and 'IsDeleted' properties are included.

```csharp
public class Workspace : IReplicatedDocument
{
    public required Guid Id { get; init; }
    public required string Name { get; set; }
    public required DateTimeOffset UpdatedAt { get; set; }
    public required bool IsDeleted { get; set; }
    public List<string>? Topics { get; set; }
}
```

--------------------------------

### Configure Custom Error Types for GraphQL

Source: https://github.com/ziptility/rxdbdotnet/blob/main/README.md

Register custom exception types to be exposed as GraphQL errors. This allows for more specific error reporting to clients.

```csharp
builder.Services
    .AddGraphQLServer()
    .AddReplicatedDocument<User>(options =>
    {
        options.Errors = new List<Type>
        {
            typeof(UserNameTakenException),
            typeof(InvalidUserNameException)
        };
    });
```

--------------------------------

### Error Handling for Database Operations and Replication

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/docs/local-first-patterns.md

Handle potential errors during local database operations using try-catch blocks and subscribe to replication error events. Differentiate between offline scenarios and actual errors.

```typescript
async function handleDatabaseOperation() {
  try {
    await collection.documents.insert(newDocument);
  } catch (error) {
    if (error.name === 'OfflineError') {
      console.log('Operation queued for sync:', error);
      // Handle offline scenario (e.g., show offline indicator)
    } else {
      console.error('Database operation failed:', error);
      // Handle other types of errors (e.g., show error message)
    }
  }
}

// For replication errors
replicationState.error$.subscribe((error) => {
  if (error.name === 'NetworkError') {
    console.log('Network error occurred, will retry:', error);
    // Handle network error (e.g., show reconnecting indicator)
  } else {
    console.error('Replication error:', error);
    // Handle other types of replication errors
  }
});
```

--------------------------------

### Build Pull Query for Workspace Data

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Defines a custom pull query builder for RxGraphQLReplication. It allows for efficient data retrieval using checkpoints and selective synchronization via a 'where' clause. Align this filter with subscription topic filters for consistent syncing.

```typescript
const pullQueryBuilder = (variables?: WorkspaceFilterInput): RxGraphQLReplicationPullQueryBuilder<Checkpoint> => {
  return (checkpoint: Checkpoint | undefined, limit: number) => {
    const query = `
      query PullWorkspace($checkpoint: WorkspaceInputCheckpoint, $limit: Int!, $where: WorkspaceFilterInput) {
        pullWorkspace(checkpoint: $checkpoint, limit: $limit, where: $where) {
          documents {
            id
            name
            topics
            updatedAt
            isDeleted
          }
          checkpoint {
            lastDocumentId
            updatedAt
          }
        }
      }
    `;

    return {
      query,
      operationName: 'PullWorkspace',
      variables: {
        checkpoint,
        limit,
        where: variables,
      },
    };
  };
};
```

--------------------------------

### Enhance RxDB Schema with Indexes and Validation

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Add indexes to optimize local queries and implement validation methods for data integrity at the client-side. Custom conflict handlers can also be defined per collection.

```typescript
const userSchema = {
  ...existingSchema,
  indexes: ['email', 'workspaceId'],
  validationMethods: {
    validateEmail: (user) => {
      // Implement email validation logic
    },
  },
};

const collections = await db.addCollections({
  users: {
    schema: userSchema,
    conflictHandler: customUserConflictHandler,
  },
  // Add similar enhancements for other collections
});
```

--------------------------------

### Lint Code

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Runs ESLint to check for code quality issues and enforce coding standards. This script is implied by the presence of ESLint in devDependencies.

```bash
npm run lint
```

--------------------------------

### Custom Hook for Network Status Management

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/docs/local-first-patterns.md

A custom React hook 'useNetworkStatus' that leverages browser 'online' and 'offline' events to track and return the current network connectivity status. Provides a 'NetworkStatusIndicator' component for visual feedback.

```typescript
function useNetworkStatus() {
  const [isOnline, setIsOnline] = useState(navigator.onLine);

  useEffect(() => {
    const handleOnline = () => setIsOnline(true);
    const handleOffline = () => setIsOnline(false);

    window.addEventListener('online', handleOnline);
    window.addEventListener('offline', handleOffline);

    return () => {
      window.removeEventListener('online', handleOnline);
      window.removeEventListener('offline', handleOffline);
    };
  }, []);

  return isOnline;
}

function NetworkStatusIndicator() {
  const isOnline = useNetworkStatus();

  return (
    <Chip
      icon={isOnline ? <WifiIcon /> : <WifiOffIcon />}
      label={isOnline ? 'Online' : 'Offline'}
      color={isOnline ? 'success' : 'default'}
    />
  );
}
```

--------------------------------

### Generate TypeScript Types

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Generates TypeScript types from the GraphQL schema using GraphQL Code Generator. This script is essential for maintaining type safety between the client and server.

```bash
npm run generate
```

--------------------------------

### Custom Conflict Handler Implementation

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/docs/local-first-patterns.md

Define a custom conflict handler to resolve synchronization conflicts based on document update times. This handler is passed during collection creation.

```typescript
const myConflictHandler = (conflict) => {
  if (conflict.newDocumentState.updatedAt > conflict.realMasterState.updatedAt) {
    return conflict.newDocumentState;
  } else {
    return conflict.realMasterState;
  }
};

const collections = await db.addCollections({
  documents: {
    schema: mySchema,
    conflictHandler: myConflictHandler,
  },
});
```

--------------------------------

### Update NetworkStatus Component with Sync Details

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Enhances the NetworkStatus component to display detailed synchronization status for different services. It uses React hooks for state management and effect handling.

```typescript
const NetworkStatus: React.FC = () => {
  const isOnline = useOnlineStatus();
  const [syncStatus, setSyncStatus] = useState<Record<string, boolean>>({});

  useEffect(() => {
    // Subscribe to replication states and update syncStatus
  }, []);

  return (
    <Tooltip title={
      <Box>
        {Object.entries(syncStatus).map(([name, active]) => (
          <Typography key={name} variant="caption">
            {`${name}: ${active ? 'Syncing' : 'Synced'}`}
          </Typography>
        ))}
      </Box>
    }>
      <Chip
        icon={isOnline ? (Object.values(syncStatus).some(Boolean) ? <SyncIcon /> : <CheckCircleIcon />) : <WifiOffIcon />}
        label={isOnline ? (Object.values(syncStatus).some(Boolean) ? 'Syncing' : 'Synced') : 'Offline'}
        color={isOnline ? (Object.values(syncStatus).some(Boolean) ? 'warning' : 'success') : 'error'}
      />
    </Tooltip>
  );
};
```

--------------------------------

### Client WebSocket Connection with Authorization Header

Source: https://github.com/ziptility/rxdbdotnet/blob/main/README.md

Include the JWT token in the 'Authorization' header within the WebSocket connection parameters. This ensures the client's identity is authenticated for subscription access.

```typescript
const client = createClient({
  url: 'ws://your-api/graphql',
  connectionParams: {
    headers: {
      Authorization: `Bearer ${jwtToken}`
    }
  }
});
```

--------------------------------

### Display Online/Offline Status in React Component

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Integrates a custom hook `useOnlineStatus` into a React navigation component to display the current network status using a Chip component. The UI changes color and icon based on the online status.

```typescript
import { useOnlineStatus } from '@/hooks/useOnlineStatus';

const NavigationRail: React.FC = () => {
  const isOnline = useOnlineStatus();

  return (
    <Paper /* existing props */>
      {/* existing code */}
      <Box sx={{ p: 2 }}>
        <Chip
          icon={isOnline ? <WifiIcon /> : <WifiOffIcon />}
          label={isOnline ? 'Online' : 'Offline'}
          color={isOnline ? 'success' : 'error'}
        />
      </Box>
    </Paper>
  );
};
```

--------------------------------

### Configure Push Response Modifier

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/README.md

Defines a response modifier for the push operation in RxDB replication. This function handles server responses, transforms them into the expected RxDB format, and logs any encountered errors.

```typescript
push: {
  queryBuilder: pushQueryBuilder,
  batchSize,
  responseModifier: (response: PushWorkspacePayload): ReplicationPushHandlerResult<Workspace> => {
    if (response.errors) {
      response.errors.forEach((error) => handleError(error, 'Workspace replication push'));
    }
    return response.workspace ?? [];
  },
},
```

--------------------------------

### Centralized Error Handling with RxDB Error Codes

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

A utility function for handling errors in a TypeScript application, specifically designed to catch RxDB errors and provide user-friendly messages based on error codes like 'CONFLICT' and 'NETWORK'.

```typescript
export const handleError = (error: unknown, context: string): void => {
  console.error(`Error in ${context}:`, error);

  let errorMessage: string;

  if (error instanceof RxError) {
    switch (error.code) {
      case 'CONFLICT':
        errorMessage = 'A conflict occurred. Please refresh and try again.';
        break;
      case 'NETWORK':
        errorMessage = 'Network error. Please check your connection.';
        break;
      // Add more specific error types
      default:
        errorMessage = 'An unexpected error occurred.';
    }
  } else if (error instanceof Error) {
    errorMessage = error.message;
  } else {
    errorMessage = 'An unknown error occurred';
  }

  toast.error(errorMessage, {
    position: 'top-right',
    autoClose: 5000,
    hideProgressBar: false,
    closeOnClick: true,
    pauseOnHover: true,
    draggable: true,
  });
};
```

--------------------------------

### Handle Conflicts in CRUD Operations with TypeScript

Source: https://github.com/ziptility/rxdbdotnet/blob/main/example/livedocs-client/ROADMAP.md

Enhance a custom hook to catch and handle 'CONFLICT' errors during upsert operations. This allows for implementing custom conflict resolution logic, such as displaying a UI for the user.

```typescript
const useDocuments = <T extends Document>(collectionName: keyof LiveDocsDatabase) => {
  // ... existing code ...

  const upsertDocument = async (doc: T) => {
    try {
      await collection.upsert(doc);
    } catch (error) {
      if (error.code === 'CONFLICT') {
        // Handle conflict, possibly by showing a conflict resolution UI
        const conflictedDoc = await collection.findOne(doc.id).exec();
        // Implement logic to resolve conflict
      }
      // Handle other types of errors
    }
  };

  // Implement similar conflict handling for other operations
};
```
Tokens:
Raw