Mandatory shapeKey on syncShapeToTable; allow shapeKey to be null

.changeset/cold-bobcats-travel.md

@@ -0,0 +1,5 @@
+---
+'@electric-sql/pglite-sync': patch
+---
+
+shapeKey in syncShapeToTable is now mandatory but nullable; passing null will not persist the shape

docs/docs/sync.md

@@ -88,8 +88,8 @@ It takes the following options as an object:
 - `primaryKey: string[]`<br>
   An array of column names that form the primary key of the table you are syncing into. Used for updates and deletes.
 
-- `shapeKey: string`<br>
-  Optional identifier for the shape subscription - if provided the stream state will be persisted along with the data in order to allow resuming the stream between sessions.
+- `shapeKey: string | null`<br>
+  Identifier for the shape subscription - If not null, stream state will be persisted along with the data in order to allow resuming the stream between sessions.
 
 - `useCopy: boolean`<br>
   Whether to use the `COPY FROM` command to insert the initial data, defaults to `false`. This process may be faster than inserting row by row as it combines the inserts into a CSV to be passed to Postgres.

packages/pglite-sync/src/index.ts

@@ -40,7 +40,7 @@ export interface SyncShapeToTableOptions {
   schema?: string
   mapColumns?: MapColumns
   primaryKey: string[]
-  shapeKey?: ShapeKey
+  shapeKey: ShapeKey | null
   useCopy?: boolean
   commitGranularity?: CommitGranularity
   commitThrottle?: number
@@ -110,7 +110,7 @@ async function createPlugin(
       shapePerTableLock.set(options.table)
       let shapeSubState: ShapeSubscriptionState | null = null
 
-      // if shapeKey is provided, ensure persistence of shape subscription
+      // if shapeKey is not null, ensure persistence of shape subscription
       // state is possible and check if it is already persisted
       if (options.shapeKey) {
         shapeSubState = await getShapeSubscriptionState({

packages/pglite-sync/test/sync.test.ts

@@ -58,6 +58,7 @@ describe('pglite-sync', () => {
       },
       table: 'todo',
       primaryKey: ['id'],
+      shapeKey: null,
     })
 
     // insert
@@ -130,6 +131,7 @@ describe('pglite-sync', () => {
       },
       table: 'todo',
       primaryKey: ['id'],
+      shapeKey: null,
     })
 
     const numInserts = 10000
@@ -397,6 +399,7 @@ describe('pglite-sync', () => {
       },
       table: table,
       primaryKey: ['id'],
+      shapeKey: null,
     })
 
     // should throw if syncing more shapes into same table
@@ -409,6 +412,7 @@ describe('pglite-sync', () => {
           },
           table: table,
           primaryKey: ['id'],
+          shapeKey: null,
         }),
     ).rejects.toThrowError(`Already syncing shape for table ${table}`)
 
@@ -420,6 +424,7 @@ describe('pglite-sync', () => {
       },
       table: altTable,
       primaryKey: ['id'],
+      shapeKey: null,
     })
     altShape.unsubscribe()
 
@@ -434,6 +439,7 @@ describe('pglite-sync', () => {
       },
       table: table,
       primaryKey: ['id'],
+      shapeKey: null,
     })
     shape2.unsubscribe()
   })
@@ -454,6 +460,7 @@ describe('pglite-sync', () => {
       },
       table: 'todo',
       primaryKey: ['id'],
+      shapeKey: null,
     })
 
     // insert
@@ -543,6 +550,7 @@ describe('pglite-sync', () => {
       },
       table: 'test_syncing',
       primaryKey: ['id'],
+      shapeKey: null,
     })
 
     await feedMessage({
@@ -589,6 +597,7 @@ describe('pglite-sync', () => {
       table: 'todo',
       primaryKey: ['id'],
       useCopy: true,
+      shapeKey: null,
     })
 
     // Create a batch of insert messages followed by an update
@@ -668,6 +677,7 @@ describe('pglite-sync', () => {
       table: 'todo',
       primaryKey: ['id'],
       useCopy: true,
+      shapeKey: null,
     })
 
     const specialCharMessages: Message[] = [
@@ -765,6 +775,7 @@ describe('pglite-sync', () => {
       table: 'todo',
       primaryKey: ['id'],
       commitGranularity: batchSize,
+      shapeKey: null,
     })
 
     // Create test messages - 7 total (should see batch of 5, then 2)
@@ -956,6 +967,7 @@ describe('pglite-sync', () => {
       table: 'todo',
       primaryKey: ['id'],
       commitGranularity: 'up-to-date',
+      shapeKey: null,
     })
 
     // Send multiple messages
@@ -1035,6 +1047,7 @@ describe('pglite-sync', () => {
       table: 'todo',
       primaryKey: ['id'],
       commitGranularity: 'operation',
+      shapeKey: null,
     })
 
     // Send multiple messages
@@ -1120,6 +1133,7 @@ describe('pglite-sync', () => {
       primaryKey: ['id'],
       commitGranularity: 'operation',
       commitThrottle: throttleMs,
+      shapeKey: null,
     })
 
     // Send messages with 10ms delays between them
@@ -1209,6 +1223,7 @@ describe('pglite-sync', () => {
       table: 'todo',
       primaryKey: ['id'],
       onInitialSync,
+      shapeKey: null,
     })
 
     // Send some initial data