Diagnostics app

demos/diagnostics-app/.gitignore

@@ -0,0 +1,47 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# ide 
+.idea
+.fleet
+.vscode
+
+# PWA
+**/public/workbox-*.js
+**/public/sw.js
+**/public/swe-worker-*
+**/public/worker-*.js
+**/public/fallback-*.js

demos/diagnostics-app/CHANGELOG.md

@@ -0,0 +1,11 @@
+# diagnostics-app
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [9bf5a76]
+  - @journeyapps/powersync-react@1.1.0
+  - @journeyapps/powersync-sdk-web@0.3.3
+
+## 0.0.1

demos/diagnostics-app/README.md

@@ -0,0 +1,69 @@
+# Diagnostics app
+
+This diagnostics app presents data from the perspective of a specific user (no server-side stats) and can be used to:
+- See stats about the user's local database.
+- Inspect tables and sync buckets on the device.
+- Identify common issues.
+- Get started quickly - play around with a SQLite database without creating an app.
+- Serve as a baseline to compare your own apps against if you run into issues such as slow sync.
+
+The app is currently available as a local standalone web app, and is largely based on the [web SDK](/packages/powersync-sdk-web/).
+
+## Running the app
+
+cd into this directory and run:
+```
+pnpm install
+pnpm start
+```
+
+Generate a [development token](https://docs.powersync.com/usage/installation/authentication-setup/development-tokens) and sign in. For development tokens, the PowerSync endpoint should be populated automatically. For some others like Supabase tokens, it needs to be entered manually.
+
+**Note**: Please see the known usability issues listed below.
+
+## Functionality
+
+### Database stats
+
+Details about the user's local database:
+
+![](public/images/diagnostics-app-stats.png)
+
+### Detected tables
+
+This only includes tables with synced data (tables with 0 synced rows won’t be present):
+
+![](public/images/diagnostics-app-detected-tables.png)
+
+### Sync buckets
+
+![](public/images/diagnostics-app-buckets.png)
+
+Similar to tables above, this only includes buckets with synced data.
+When syncing large amounts of data:
+- Total operations is calculated from the checkpoint, will be populated quickly.
+- Other stats are populated as the data is downloaded, so this may take a while.
+
+### Dynamic schema
+The schema is dynamically generated and automatically updated from downloaded data. The schema used is displayed in a separate page:
+
+![](public/images/diagnostics-app-schema.png)
+
+This does mean that if a table has 0 synced rows, it won’t be present in the schema, and queries referencing it will fail.
+
+Tables and columns are only added to this schema - nothing is automatically removed when removed from sync rules. To refresh the schema, use the “Clear & Redownload” button on the main page.
+
+### SQL console
+Same functionality as in the other demo apps:
+
+![](public/images/diagnostics-app-sql-console.png)
+
+## Known issues
+At this stage, we recommend running the app with the dev console open, as some errors are currently not being surfaced to the UI, including:
+* No errors are displayed when the token is invalid, or when it expires later.
+    - The user is also “logged in” to the app with an invalid token after an initial delay
+* If the query in the SQL console contains an error, nothing is displayed.
+
+Other known issues:
+- When signed out, there is no automatic redirect to the login page.
+- When a lot of data is synced, the main dashboard may be slow.

demos/diagnostics-app/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@journeyapps/powersync-diagnostics-app",
+  "version": "0.1.1",
+  "private": true,
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "start": "pnpm build && pnpm preview"
+  },
+  "dependencies": {
+    "@journeyapps/powersync-react": "workspace:*",
+    "@journeyapps/powersync-sdk-web": "workspace:*",
+    "@journeyapps/wa-sqlite": "~0.1.1",
+    "@mui/material": "^5.15.12",
+    "@mui/x-data-grid": "^6.19.6",
+    "js-logger": "^1.6.1",
+    "lodash": "^4.17.21",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router-dom": "^6.22.3"
+  },
+  "devDependencies": {
+    "@types/lodash": "^4.14.202",
+    "@types/node": "^20.11.25",
+    "@types/react": "^18.2.64",
+    "@types/react-dom": "^18.2.21",
+    "@vitejs/plugin-react": "^4.2.1",
+    "autoprefixer": "^10.4.18",
+    "babel-loader": "^9.1.3",
+    "typescript": "^5.4.2",
+    "vite": "^5.1.5",
+    "vite-plugin-pwa": "^0.19.2",
+    "vite-plugin-top-level-await": "^1.4.1",
+    "vite-plugin-wasm": "^3.3.0"
+  }
+}

demos/diagnostics-app/src/app/globals.css

@@ -0,0 +1,12 @@
+:root {
+  --foreground-rgb: 255, 255, 255;
+  --background-start-rgb: 0, 0, 0;
+  --background-end-rgb: 0, 0, 0;
+}
+
+body {
+  color: rgb(var(--foreground-rgb));
+  min-height: 100vh;
+  margin: 0;
+  background: linear-gradient(to bottom, transparent, rgb(var(--background-end-rgb))) rgb(var(--background-start-rgb));
+}

demos/diagnostics-app/src/app/index.tsx

@@ -0,0 +1,18 @@
+import { createRoot } from 'react-dom/client';
+import { RouterProvider } from 'react-router-dom';
+import { SystemProvider } from '../components/providers/SystemProvider';
+import { ThemeProviderContainer } from '../components/providers/ThemeProviderContainer';
+import { router } from './router';
+
+const root = createRoot(document.getElementById('app')!);
+root.render(<App />);
+
+export function App() {
+  return (
+    <ThemeProviderContainer>
+      <SystemProvider>
+        <RouterProvider router={router} />
+      </SystemProvider>
+    </ThemeProviderContainer>
+  );
+}

demos/diagnostics-app/src/app/login.tsx

@@ -0,0 +1,19 @@
+import React from 'react';
+import { LoginDetailsWidget } from '@/components/widgets/LoginDetailsWidget';
+import { useNavigate } from 'react-router-dom';
+import { DEFAULT_ENTRY_ROUTE } from '@/app/router';
+import { connector } from '@/library/powersync/ConnectionManager';
+
+export default function LoginPage() {
+  const navigate = useNavigate();
+
+  return (
+    <LoginDetailsWidget
+      onSubmit={async (values) => {
+        await connector.signIn(values);
+
+        navigate(DEFAULT_ENTRY_ROUTE);
+      }}
+    />
+  );
+}

demos/diagnostics-app/src/app/page.tsx

@@ -0,0 +1,46 @@
+import React from 'react';
+import { CircularProgress, Grid, styled } from '@mui/material';
+import { useNavigate } from 'react-router-dom';
+import { DEFAULT_ENTRY_ROUTE, LOGIN_ROUTE } from './router';
+import { connector } from '@/library/powersync/ConnectionManager';
+
+export type LoginFormParams = {
+  email: string;
+  password: string;
+};
+
+/**
+ * This page shows a loading spinner we detect a session
+ * and redirect either to the app or auth flow.
+ */
+export default function EntryPage() {
+  const navigate = useNavigate();
+
+  React.useEffect(() => {
+    if (connector.hasCredentials()) {
+      navigate(DEFAULT_ENTRY_ROUTE);
+    } else {
+      navigate(LOGIN_ROUTE);
+    }
+  }, []);
+
+  return (
+    <S.MainGrid container>
+      <S.CenteredGrid item xs={12} md={6} lg={5}>
+        <CircularProgress />
+      </S.CenteredGrid>
+    </S.MainGrid>
+  );
+}
+
+namespace S {
+  export const CenteredGrid = styled(Grid)`
+    display: flex;
+    justify-content: center;
+    align-items: center;
+  `;
+
+  export const MainGrid = styled(CenteredGrid)`
+    min-height: 100vh;
+  `;
+}

demos/diagnostics-app/src/app/router.tsx

@@ -0,0 +1,49 @@
+import { Outlet, createBrowserRouter } from 'react-router-dom';
+import LoginPage from './login';
+import EntryPage from './page';
+import ViewsLayout from './views/layout';
+import SQLConsolePage from './views/sql-console';
+import SyncDiagnosticsPage from './views/sync-diagnostics';
+import SchemaPage from './views/schema';
+
+export const LOGIN_ROUTE = '/login';
+export const SQL_CONSOLE_ROUTE = '/sql-console';
+export const SYNC_DIAGNOSTICS_ROUTE = '/sync-diagnostics';
+export const SCHEMA_ROUTE = '/schema';
+
+/**
+ * Navigate to this route after authentication
+ */
+export const DEFAULT_ENTRY_ROUTE = SYNC_DIAGNOSTICS_ROUTE;
+
+export const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <EntryPage />
+  },
+  {
+    path: LOGIN_ROUTE,
+    element: <LoginPage />
+  },
+  {
+    element: (
+      <ViewsLayout>
+        <Outlet />
+      </ViewsLayout>
+    ),
+    children: [
+      {
+        path: SQL_CONSOLE_ROUTE,
+        element: <SQLConsolePage />
+      },
+      {
+        path: SYNC_DIAGNOSTICS_ROUTE,
+        element: <SyncDiagnosticsPage />
+      },
+      {
+        path: SCHEMA_ROUTE,
+        element: <SchemaPage />
+      }
+    ]
+  }
+]);