├── .eslintrc.js ├── .gitignore ├── .prettierrc ├── LICENSE ├── README.md ├── package-lock.json ├── package.json ├── src └── index.ts └── tsconfig.json /.eslintrc.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | env: { 3 | browser: true, 4 | es2021: true, 5 | node: true, 6 | }, 7 | extends: [ 8 | `eslint:recommended`, 9 | `plugin:@typescript-eslint/recommended`, 10 | `plugin:react/recommended`, 11 | `plugin:prettier/recommended`, 12 | ], 13 | parserOptions: { 14 | ecmaVersion: 2022, 15 | requireConfigFile: false, 16 | sourceType: `module`, 17 | ecmaFeatures: { 18 | jsx: true, 19 | }, 20 | }, 21 | settings: { 22 | react: { 23 | version: `detect`, 24 | }, 25 | }, 26 | parser: '@typescript-eslint/parser', 27 | plugins: [`react`, `prettier`], 28 | rules: { 29 | quotes: [`error`, `backtick`], 30 | }, 31 | } 32 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | lerna-debug.log* 8 | .pnpm-debug.log* 9 | 10 | # Diagnostic reports (https://nodejs.org/api/report.html) 11 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json 12 | 13 | # Runtime data 14 | pids 15 | *.pid 16 | *.seed 17 | *.pid.lock 18 | 19 | # Directory for instrumented libs generated by jscoverage/JSCover 20 | lib-cov 21 | 22 | # Coverage directory used by tools like istanbul 23 | coverage 24 | *.lcov 25 | 26 | # nyc test coverage 27 | .nyc_output 28 | 29 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) 30 | .grunt 31 | 32 | # Bower dependency directory (https://bower.io/) 33 | bower_components 34 | 35 | # node-waf configuration 36 | .lock-wscript 37 | 38 | # Compiled binary addons (https://nodejs.org/api/addons.html) 39 | build/Release 40 | 41 | # Dependency directories 42 | node_modules/ 43 | jspm_packages/ 44 | 45 | # Snowpack dependency directory (https://snowpack.dev/) 46 | web_modules/ 47 | 48 | # TypeScript cache 49 | *.tsbuildinfo 50 | 51 | # Optional npm cache directory 52 | .npm 53 | 54 | # Optional eslint cache 55 | .eslintcache 56 | 57 | # Optional stylelint cache 58 | .stylelintcache 59 | 60 | # Microbundle cache 61 | .rpt2_cache/ 62 | .rts2_cache_cjs/ 63 | .rts2_cache_es/ 64 | .rts2_cache_umd/ 65 | 66 | # Optional REPL history 67 | .node_repl_history 68 | 69 | # Output of 'npm pack' 70 | *.tgz 71 | 72 | # Yarn Integrity file 73 | .yarn-integrity 74 | 75 | # dotenv environment variable files 76 | .env 77 | .env.development.local 78 | .env.test.local 79 | .env.production.local 80 | .env.local 81 | 82 | # parcel-bundler cache (https://parceljs.org/) 83 | .cache 84 | .parcel-cache 85 | 86 | # Next.js build output 87 | .next 88 | out 89 | 90 | # Nuxt.js build / generate output 91 | .nuxt 92 | dist 93 | 94 | # Gatsby files 95 | .cache/ 96 | # Comment in the public line in if your project uses Gatsby and not Next.js 97 | # https://nextjs.org/blog/next-9-1#public-directory-support 98 | # public 99 | 100 | # vuepress build output 101 | .vuepress/dist 102 | 103 | # vuepress v2.x temp and cache directory 104 | .temp 105 | .cache 106 | 107 | # Docusaurus cache and generated files 108 | .docusaurus 109 | 110 | # Serverless directories 111 | .serverless/ 112 | 113 | # FuseBox cache 114 | .fusebox/ 115 | 116 | # DynamoDB Local files 117 | .dynamodb/ 118 | 119 | # TernJS port file 120 | .tern-port 121 | 122 | # Stores VSCode versions used for testing VSCode extensions 123 | .vscode-test 124 | 125 | # yarn v2 126 | .yarn/cache 127 | .yarn/unplugged 128 | .yarn/build-state.yml 129 | .yarn/install-state.gz 130 | .pnp.* 131 | -------------------------------------------------------------------------------- /.prettierrc: -------------------------------------------------------------------------------- 1 | { 2 | "trailingComma": "es5", 3 | "semi": false, 4 | "tabWidth": 2 5 | } 6 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024 Kyle Mathews 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # electric-query 2 | Library for deeply integrating [ElectricSQL](https://electric-sql.com/) partial syncing and queries with your React app routes. 3 | 4 | ## Install 5 | 6 | `npm install electric-query` 7 | 8 | ## Why 9 | 10 | This library makes it easy to sync and query the exact data that's needed for each route. 11 | 12 | The simplest way to build an ElectricSQL app is to sync upfront all data. But this gets slow as for larger apps. So just like code splitting, you can split data syncing along route boundaries so the user waits for only the minimal amount of data to be synced. 13 | 14 | ElectricSQL has this concept of “[Shapes](https://electric-sql.com/docs/usage/data-access/shapes)” — which let you declare the shape of data you want synced to construct a particular route’s UI. It’s basically the declarative equivalent of making an API call (an imperative operation). Instead of saying “fetch this shape of data”, you say “sync this shape of data”. You get the same initial load but ElectricSQL also ensures any updates across the system continue to get synced to you in real-time. 15 | 16 | ## Usage 17 | 18 | The library exposes an `initElectric` function which takes care of initializing 19 | Electric. 20 | 21 | ```ts 22 | import { initElectric, setLoggedOut } from "electric-query" 23 | import { Electric, schema } from "./generated/client" 24 | import sqliteWasm from "wa-sqlite/dist/wa-sqlite-async.wasm?asset" 25 | 26 | if (loggedIn) { 27 | const electric = await initElectric({ 28 | appName: `my-app`, 29 | schema, 30 | sqliteWasmPath: sqliteWasm, 31 | config: { 32 | auth: { 33 | token, 34 | }, 35 | debug: false, //DEBUG_MODE, 36 | url: electricUrl, 37 | }, 38 | }) 39 | } else { 40 | setLoggedOut() 41 | } 42 | ``` 43 | 44 | In the `loader` (or equivalent) function for each route, you define the sync shapes 45 | and queries for each route. Electric Query ensures both are finished before 46 | calling your route component. This means the new route can immediately render 47 | without any blinking. 48 | 49 | ```ts 50 | // In routes 51 | const routes = [ 52 | ...otherRoutes, 53 | { 54 | path: `/type/:id`, 55 | element: , 56 | loader: async (props) => { 57 | const url = new URL(props.request.url) 58 | const key = url.pathname + url.search 59 | await electricSqlLoader({ 60 | key, 61 | shapes: ({ db }) => [ 62 | { 63 | shape: db.youtube_videos.sync(), 64 | // Check that at least one video is synced. 65 | // Eventually Electric will probably have metadata on synced status 66 | // we can check. 67 | isReady: async () => !!(await db.youtube_videos.findFirst()), 68 | }, 69 | ], 70 | queries: ({ db }) => Video.queries({ db, id: props.params.videoId }), 71 | }) 72 | 73 | return null 74 | }, 75 | }, 76 | ] 77 | ``` 78 | 79 | Each route component then uses an `useElectricData` hook to get the results 80 | of the queries. 81 | 82 | For easy reading, we suggest you write component queries alongside the UI code. 83 | 84 | ```ts 85 | // In route components 86 | import { useElectricData } from "electric-query" 87 | import { useLocation } from "react-router-dom" 88 | import { Electric, schema } from "../generated/client" 89 | 90 | const queries = ({ db }: { db: Electric[`db`] }) => { 91 | return { 92 | foo: db.my_table.liveMany(), 93 | } 94 | } 95 | 96 | export default function Component() { 97 | const location = useLocation() 98 | const { foo } = useElectricData(location.pathname + location.search) 99 | 100 | return JSON.stringify(foo, null, 4) 101 | } 102 | 103 | Component.queries = queries 104 | ``` 105 | 106 | For a full example of using this library, see this starter https://github.com/KyleAMathews/vite-react-router-electric-sql-starter 107 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "electric-query", 3 | "description": "Library for integrating ElectricSQL queries with your (React) routes", 4 | "version": "0.0.14", 5 | "author": "Kyle Mathews ", 6 | "bugs": { 7 | "url": "https://github.com/KyleAMathews/electric-query/issues" 8 | }, 9 | "dependencies": { 10 | "browser-tab-id": "^0.0.8", 11 | "page-lifecycle": "^0.1.2" 12 | }, 13 | "devDependencies": { 14 | "@typescript-eslint/eslint-plugin": "^7.1.0", 15 | "@typescript-eslint/parser": "^7.1.0", 16 | "electric-sql": "^0.9.4", 17 | "eslint": "^8.57.0", 18 | "eslint-config-prettier": "^9.1.0", 19 | "eslint-config-react": "^1.1.7", 20 | "eslint-plugin-prettier": "^5.1.3", 21 | "eslint-plugin-react": "^7.33.2", 22 | "prettier": "^3.2.5", 23 | "shx": "^0.3.4", 24 | "tsup": "^8.0.2", 25 | "typescript": "^5.3.3", 26 | "wa-sqlite": "^0.9.9" 27 | }, 28 | "exports": { 29 | ".": { 30 | "types": { 31 | "import": "./dist/index.d.mts", 32 | "require": "./dist/index.d.ts" 33 | }, 34 | "import": "./dist/index.mjs", 35 | "require": "./dist/index.cjs" 36 | }, 37 | "./package.json": "./package.json" 38 | }, 39 | "main": "./dist/index.cjs", 40 | "module": "./dist/index.mjs", 41 | "types": "./dist/index.d.ts", 42 | "files": [ 43 | "dist" 44 | ], 45 | "homepage": "https://github.com/KyleAMathews/electric-query#readme", 46 | "keywords": [ 47 | "electric-sql" 48 | ], 49 | "license": "MIT", 50 | "repository": { 51 | "type": "git", 52 | "url": "git+https://github.com/KyleAMathews/electric-query.git" 53 | }, 54 | "scripts": { 55 | "build": "npm run clean && tsup --external electric-sql/wa-sqlite --external electric-sql/react", 56 | "check": "tsc", 57 | "clean": "shx rm -rf dist *.d.ts", 58 | "prepublishOnly": "npm run build", 59 | "test": "vitest" 60 | }, 61 | "tsup": { 62 | "entry": [ 63 | "src/index.ts" 64 | ], 65 | "format": [ 66 | "esm", 67 | "cjs" 68 | ], 69 | "dts": true 70 | } 71 | } 72 | -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- 1 | import { useLiveQuery } from "electric-sql/react" 2 | import { SatelliteErrorCode } from "electric-sql/util" 3 | import { ElectricDatabase, electrify } from "electric-sql/wa-sqlite" 4 | import { TabIdCoordinator } from "browser-tab-id" 5 | import { ElectricConfig } from "electric-sql/config" 6 | import lifecycle from "page-lifecycle" 7 | 8 | type GetTokenFunction = () => Promise 9 | 10 | interface InitElectricParams { 11 | appName: string 12 | sqliteWasmPath: string 13 | schema: any 14 | config: ElectricConfig 15 | token: string 16 | getToken?: GetTokenFunction 17 | } 18 | 19 | // Get our tabId 20 | const tabIdCoordinator = new TabIdCoordinator() 21 | 22 | let electricResolve: (value: unknown) => void 23 | let electricReject: (value: unknown) => void 24 | const electricPromise = new Promise((resolve, reject) => { 25 | electricResolve = resolve 26 | electricReject = reject 27 | }) 28 | 29 | export function setLoggedOut() { 30 | electricReject(`not logged in`) 31 | } 32 | 33 | export async function initElectric(params: InitElectricParams) { 34 | const { appName, sqliteWasmPath, schema, config } = params 35 | const tabId = tabIdCoordinator.tabId 36 | const tabScopedDbName = `${appName}-${tabId}.db` 37 | console.log({ tabScopedDbName }) 38 | 39 | const conn = await ElectricDatabase.init(tabScopedDbName, sqliteWasmPath) 40 | const electric = await electrify(conn, schema, config) 41 | 42 | // Connect to Electric 43 | await electric.connect(params.token) 44 | console.log(`connected`, { token: params.token }) 45 | 46 | if (params.getToken) { 47 | // Subscribe to connectivity changes to detect JWT expiration 48 | electric.notifier.subscribeToConnectivityStateChanges(async (event) => { 49 | console.log({ event }) 50 | if ( 51 | typeof params.getToken === `function` && 52 | event.connectivityState.status === `disconnected` && 53 | event.connectivityState.reason?.code === SatelliteErrorCode.AUTH_EXPIRED 54 | ) { 55 | console.log(`JWT expired, reconnecting...`) 56 | const newToken = await params.getToken() 57 | await electric.connect(newToken) 58 | console.log(`connection restored`) 59 | } 60 | }) 61 | 62 | lifecycle.addEventListener(`statechange`, async function (event) { 63 | if (event.newState === `active`) { 64 | if (!electric.isConnected) { 65 | if (params.getToken) { 66 | const newToken = await params.getToken() 67 | await electric.connect(newToken) 68 | console.log(`reconnected`) 69 | } 70 | } 71 | } 72 | }) 73 | } 74 | 75 | electricResolve(electric) 76 | 77 | return electric 78 | } 79 | 80 | interface ElectricWithDb { 81 | db: any 82 | } 83 | 84 | type ShapeFunction = (params: { 85 | db: Electric[`db`] 86 | }) => Array<{ 87 | shape: Promise 88 | isReady: () => Promise 89 | }> 90 | 91 | type QueriesRecord = ( 92 | params: { db: Electric[`db`] } & { [key: string]: any } 93 | ) => Record | (() => Record) 94 | 95 | type QueryFunction = () => Promise 96 | 97 | // Define everything in loaders w/ a key & then the hook just references that key 98 | const routeCache = new Map() 99 | const queriesMap = new Map() 100 | 101 | export async function electricSqlLoader({ 102 | key, 103 | shapes, 104 | queries, 105 | }: { 106 | key: string 107 | shapes: ShapeFunction 108 | queries: QueriesRecord 109 | }) { 110 | console.time(`loading ${key}`) 111 | 112 | // Wait for Electric to be active 113 | let electric 114 | try { 115 | electric = (await electricPromise) as Electric 116 | } catch (e) { 117 | return 118 | } 119 | 120 | const { db } = electric 121 | 122 | const resolvedShapes = shapes({ db }) 123 | 124 | async function syncTables() { 125 | const syncPromises = await Promise.all( 126 | resolvedShapes.map((shape) => shape.shape) 127 | ) 128 | await Promise.all(syncPromises.map((shape) => shape.synced)) 129 | } 130 | 131 | let isReadies = [false] 132 | try { 133 | isReadies = await Promise.all( 134 | resolvedShapes.map((shape) => shape.isReady()) 135 | ) 136 | } catch (e) { 137 | console.log(`a isReady failed... so probably it's not ready`, e) 138 | } 139 | 140 | // Check if all isReadies are true 141 | if (isReadies.every((isReady) => isReady === true)) { 142 | // Start syncing but don't block rendering the app on it. 143 | Promise.resolve().then(() => syncTables()) 144 | } else { 145 | await syncTables() 146 | } 147 | 148 | let setupQueries = queries({ db }) 149 | if (typeof setupQueries === `function`) { 150 | setupQueries = setupQueries() 151 | } 152 | 153 | queriesMap.set(key, setupQueries) 154 | 155 | // Run queries 156 | const promises = Object.entries(setupQueries).map(([_key, func]) => { 157 | if (typeof func === `function`) { 158 | return func() 159 | // I.e. it is a promise from db.raw 160 | } else { 161 | return Promise.resolve(func).then((result) => { 162 | return { result } 163 | }) 164 | } 165 | }) 166 | const resolvedPromises = await Promise.all(promises) 167 | const queryResults = Object.fromEntries( 168 | resolvedPromises.map((result, i) => [ 169 | Object.keys(setupQueries)[i], 170 | result.result, 171 | ]) 172 | ) 173 | 174 | routeCache.set(key, queryResults) 175 | console.timeEnd(`loading ${key}`) 176 | } 177 | 178 | export function useElectricData(key: string) { 179 | const queriesMapResult = queriesMap.get(key) 180 | 181 | if (!queriesMapResult) { 182 | throw new Error(`Queries not found for ${key}.`) 183 | } 184 | 185 | const cachedResult = routeCache.get(key) 186 | 187 | if (!cachedResult) { 188 | throw new Error( 189 | `precached query results not found for ${key}. Check your loader code to make sure it's caching correctly` 190 | ) 191 | } 192 | 193 | // Call useLiveQuery for each query. 194 | const results = Object.keys(queriesMapResult).map((key) => { 195 | const query = queriesMapResult[key] 196 | let resultsReal 197 | if (typeof query === `function`) { 198 | // We're living dangerously. 199 | // eslint-disable-next-line 200 | const { results } = useLiveQuery(query); 201 | resultsReal = results 202 | } else { 203 | resultsReal = cachedResult[key] 204 | } 205 | return [key, resultsReal] 206 | }) 207 | 208 | // Use cached results until all the live queries 209 | // have returned results. 210 | if (results.some((r) => r[1] === undefined)) { 211 | return cachedResult 212 | } else { 213 | return Object.fromEntries(results) 214 | } 215 | } 216 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "ES2020", 4 | "useDefineForClassFields": true, 5 | "lib": ["ES2020", "DOM", "DOM.Iterable"], 6 | "module": "ESNext", 7 | "skipLibCheck": true, 8 | 9 | /* Bundler mode */ 10 | "moduleResolution": "node", 11 | "allowImportingTsExtensions": true, 12 | "resolveJsonModule": true, 13 | "isolatedModules": true, 14 | "noEmit": true, 15 | "jsx": "react-jsx", 16 | 17 | /* Linting */ 18 | "strict": true, 19 | "strictNullChecks": true, 20 | "noUnusedLocals": true, 21 | "noUnusedParameters": true, 22 | "noFallthroughCasesInSwitch": true 23 | }, 24 | "include": ["src"] 25 | } 26 | --------------------------------------------------------------------------------