Open History to see the last commit
1import {
2 ShapeStream,
3 isChangeMessage,
4 isControlMessage,
5} from "@electric-sql/client"
6import { Store } from "@tanstack/store"
7import type { SyncConfig } from "@tanstack/optimistic"
8import type {
9 ControlMessage,
10 Message,
11 Row,
12 ShapeStreamOptions,
13} from "@electric-sql/client"
14
15// Re-exports
16export type * from "@tanstack/optimistic"
17export * from "./useCollection"
18export type { Collection } from "@tanstack/optimistic"
19
20/**
21 * Extended SyncConfig interface with ElectricSQL-specific functionality
22 */
23export interface ElectricSync extends SyncConfig {
24 /**
25 * Wait for a specific transaction ID to be synced
26 * @param txid The transaction ID to wait for
27 * @param timeout Optional timeout in milliseconds (defaults to 30000ms)
28 * @returns Promise that resolves when the txid is synced
29 */
30 awaitTxid: (txid: number, timeout?: number) => Promise<boolean>
31
32 /**
33 * Get the sync metadata for insert operations
34 * @returns Record containing primaryKey and relation information
35 */
36 getSyncMetadata: () => Record<string, unknown>
37}
38
39function isUpToDateMessage<T extends Row<unknown> = Row>(
40 message: Message<T>
41): message is ControlMessage & { up_to_date: true } {
42 return isControlMessage(message) && message.headers.control === `up-to-date`
43}
44
45// Check if a message contains txids in its headers
46function hasTxids<T extends Row<unknown> = Row>(
47 message: Message<T>
48): message is Message<T> & { headers: { txids?: Array<number> } } {
49 return (
50 `headers` in message &&
51 `txids` in message.headers &&
52 Array.isArray(message.headers.txids)
53 )
54}
55
56/**
57 * Creates an ElectricSQL sync configuration
58 *
59 * @param streamOptions - Configuration options for the ShapeStream
60 * @param options - Options for the ElectricSync configuration
61 * @returns ElectricSync configuration
62 */
63export function createElectricSync<T extends Row<unknown> = Row>(
64 streamOptions: ShapeStreamOptions,
65 options: ElectricSyncOptions
66): ElectricSync {
67 const { primaryKey } = options
68
69 // Create a store to track seen txids
70 const seenTxids = new Store<Set<number>>(new Set())
71
72 // Store for the relation schema information
73 const relationSchema = new Store<string | undefined>(undefined)
74
75 // Function to check if a txid has been seen
76 const hasTxid = (txid: number): boolean => {
77 return seenTxids.state.has(txid)
78 }
79
80 // Function to await a specific txid
81 const awaitTxid = async (txid: number, timeout = 30000): Promise<boolean> => {
82 // If we've already seen this txid, resolve immediately
83 if (hasTxid(txid)) {
84 return true
85 }
86
87 // Otherwise, create a promise that resolves when the txid is seen
88 return new Promise<boolean>((resolve, reject) => {
89 // Set up a timeout
90 const timeoutId = setTimeout(() => {
91 unsubscribe()
92 reject(new Error(`Timeout waiting for txid: ${txid}`))
93 }, timeout)
94
95 // Subscribe to the store to watch for the txid
96 const unsubscribe = seenTxids.subscribe(() => {
97 if (hasTxid(txid)) {
98 clearTimeout(timeoutId)
99 unsubscribe()
100 resolve(true)
101 }
102 })
103 })
104 }
105
106 /**
107 * Generate a key from a row using the primaryKey columns
108 * @param row - The row data
109 * @returns A string key formed from the primary key values
110 */
111 const generateKeyFromRow = (row: T): string => {
112 // eslint-disable-next-line
113 if (!primaryKey || primaryKey.length === 0) {
114 throw new Error(`Primary key is required for Electric sync`)
115 }
116
117 return primaryKey
118 .map((key) => {
119 const value = row[key]
120 if (value === undefined) {
121 throw new Error(`Primary key column "${key}" not found in row`)
122 }
123 return String(value)
124 })
125 .join(`|`)
126 }
127
128 /**
129 * Get the sync metadata for insert operations
130 * @returns Record containing primaryKey and relation information
131 */
132 const getSyncMetadata = (): Record<string, unknown> => {
133 // Use the stored schema if available, otherwise default to 'public'
134 const schema = relationSchema.state || `public`
135
136 return {
137 primaryKey,
138 relation: streamOptions.params?.table
139 ? [schema, streamOptions.params.table]
140 : undefined,
141 }
142 }
143
144 return {
145 sync: ({ begin, write, commit }) => {
146 const stream = new ShapeStream(streamOptions)
147 let transactionStarted = false
148 let newTxids = new Set<number>()
149
150 stream.subscribe((messages: Array<Message<Row>>) => {
151 let hasUpToDate = false
152
153 for (const message of messages) {
154 // Check for txids in the message and add them to our store
155 if (hasTxids(message) && message.headers.txids) {
156 message.headers.txids.forEach((txid) => newTxids.add(txid))
157 }
158
159 // Check if the message contains schema information
160 if (isChangeMessage(message) && message.headers.schema) {
161 // Store the schema for future use if it's a valid string
162 if (typeof message.headers.schema === `string`) {
163 const schema: string = message.headers.schema
164 relationSchema.setState(() => schema)
165 }
166 }
167
168 if (isChangeMessage(message)) {
169 if (!transactionStarted) {
170 begin()
171 transactionStarted = true
172 }
173
174 // Use the message's key if available, otherwise generate one from the row using primaryKey
175 const key =
176 message.key || generateKeyFromRow(message.value as unknown as T)
177
178 // Include the primary key and relation info in the metadata
179 const enhancedMetadata = {
180 ...message.headers,
181 primaryKey,
182 }
183
184 write({
185 key,
186 type: message.headers.operation,
187 value: message.value,
188 metadata: enhancedMetadata,
189 })
190 } else if (isUpToDateMessage(message)) {
191 hasUpToDate = true
192 }
193 }
194
195 if (hasUpToDate && transactionStarted) {
196 commit()
197 seenTxids.setState((currentTxids) => {
198 const clonedSeen = new Set(currentTxids)
199 newTxids.forEach((txid) => clonedSeen.add(txid))
200
201 newTxids = new Set()
202 return clonedSeen
203 })
204 transactionStarted = false
205 }
206 })
207 },
208 // Expose the awaitTxid function
209 awaitTxid,
210 // Expose the getSyncMetadata function
211 getSyncMetadata,
212 }
213}
214
215/**
216 * Configuration options for ElectricSync
217 */
218export interface ElectricSyncOptions {
219 /**
220 * Array of column names that form the primary key of the shape
221 */
222 primaryKey: Array<string>
223}