Interface: ElectricCollectionConfig<TExplicit, TSchema, TFallback>

Defined in: packages/electric-db-collection/src/electric.ts:73

Configuration interface for Electric collection options

Remarks

Type resolution follows a priority order:

If you provide an explicit type via generic parameter, it will be used
If no explicit type is provided but a schema is, the schema's output type will be inferred
If neither explicit type nor schema is provided, the fallback type will be used

You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.

Type Parameters

• TExplicit extends Row<unknown> = Row<unknown>

The explicit type of items in the collection (highest priority)

• TSchema extends StandardSchemaV1 = never

The schema type for validation and type inference (second priority)

• TFallback extends Row<unknown> = Row<unknown>

The fallback type if no explicit or schema type is provided

Properties

getKey()

getKey: (item) => string | number;

getKey: (item) => string | number;

Defined in: packages/electric-db-collection/src/electric.ts:90

Parameters

item

ResolveType

Returns

string | number

id?

optional id: string;

optional id: string;

Defined in: packages/electric-db-collection/src/electric.ts:88

All standard Collection configuration properties

onDelete()?

optional onDelete: (params) => Promise<{
  txid: number | number[];
}>;

optional onDelete: (params) => Promise<{
  txid: number | number[];
}>;

Defined in: packages/electric-db-collection/src/electric.ts:246

Optional asynchronous handler function called before a delete operation Must return an object containing a txid number or array of txids

Parameters

params

DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>

Object containing transaction and collection information

Returns

Promise<{ txid: number | number[]; }>

Promise resolving to an object with txid or txids

Examples

// Basic Electric delete handler - MUST return { txid: number }
onDelete: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  const result = await api.todos.delete({
    id: mutation.original.id
  })
  return { txid: result.txid } // Required for Electric sync matching
}

// Basic Electric delete handler - MUST return { txid: number }
onDelete: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  const result = await api.todos.delete({
    id: mutation.original.id
  })
  return { txid: result.txid } // Required for Electric sync matching
}

// Delete handler with multiple items - return array of txids
onDelete: async ({ transaction }) => {
  const deletes = await Promise.all(
    transaction.mutations.map(m =>
      api.todos.delete({
        where: { id: m.key }
      })
    )
  )
  return { txid: deletes.map(d => d.txid) } // Array of txids
}

// Delete handler with multiple items - return array of txids
onDelete: async ({ transaction }) => {
  const deletes = await Promise.all(
    transaction.mutations.map(m =>
      api.todos.delete({
        where: { id: m.key }
      })
    )
  )
  return { txid: deletes.map(d => d.txid) } // Array of txids
}

// Delete handler with batch operation - single txid
onDelete: async ({ transaction }) => {
  const idsToDelete = transaction.mutations.map(m => m.original.id)
  const result = await api.todos.deleteMany({
    ids: idsToDelete
  })
  return { txid: result.txid } // Single txid for batch operation
}

// Delete handler with batch operation - single txid
onDelete: async ({ transaction }) => {
  const idsToDelete = transaction.mutations.map(m => m.original.id)
  const result = await api.todos.deleteMany({
    ids: idsToDelete
  })
  return { txid: result.txid } // Single txid for batch operation
}

// Delete handler with optimistic rollback
onDelete: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  try {
    const result = await api.deleteTodo(mutation.original.id)
    return { txid: result.txid }
  } catch (error) {
    // Transaction will automatically rollback optimistic changes
    console.error('Delete failed, rolling back:', error)
    throw error
  }
}

// Delete handler with optimistic rollback
onDelete: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  try {
    const result = await api.deleteTodo(mutation.original.id)
    return { txid: result.txid }
  } catch (error) {
    // Transaction will automatically rollback optimistic changes
    console.error('Delete failed, rolling back:', error)
    throw error
  }
}

onInsert()?

optional onInsert: (params) => Promise<{
  txid: number | number[];
}>;

optional onInsert: (params) => Promise<{
  txid: number | number[];
}>;

Defined in: packages/electric-db-collection/src/electric.ts:141

Optional asynchronous handler function called before an insert operation Must return an object containing a txid number or array of txids

Parameters

params

InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>

Object containing transaction and collection information

Returns

Promise<{ txid: number | number[]; }>

Promise resolving to an object with txid or txids

Examples

// Basic Electric insert handler - MUST return { txid: number }
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  const result = await api.todos.create({
    data: newItem
  })
  return { txid: result.txid } // Required for Electric sync matching
}

// Basic Electric insert handler - MUST return { txid: number }
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  const result = await api.todos.create({
    data: newItem
  })
  return { txid: result.txid } // Required for Electric sync matching
}

// Insert handler with multiple items - return array of txids
onInsert: async ({ transaction }) => {
  const items = transaction.mutations.map(m => m.modified)
  const results = await Promise.all(
    items.map(item => api.todos.create({ data: item }))
  )
  return { txid: results.map(r => r.txid) } // Array of txids
}

// Insert handler with multiple items - return array of txids
onInsert: async ({ transaction }) => {
  const items = transaction.mutations.map(m => m.modified)
  const results = await Promise.all(
    items.map(item => api.todos.create({ data: item }))
  )
  return { txid: results.map(r => r.txid) } // Array of txids
}

// Insert handler with error handling
onInsert: async ({ transaction }) => {
  try {
    const newItem = transaction.mutations[0].modified
    const result = await api.createTodo(newItem)
    return { txid: result.txid }
  } catch (error) {
    console.error('Insert failed:', error)
    throw error // This will cause the transaction to fail
  }
}

// Insert handler with error handling
onInsert: async ({ transaction }) => {
  try {
    const newItem = transaction.mutations[0].modified
    const result = await api.createTodo(newItem)
    return { txid: result.txid }
  } catch (error) {
    console.error('Insert failed:', error)
    throw error // This will cause the transaction to fail
  }
}

// Insert handler with batch operation - single txid
onInsert: async ({ transaction }) => {
  const items = transaction.mutations.map(m => m.modified)
  const result = await api.todos.createMany({
    data: items
  })
  return { txid: result.txid } // Single txid for batch operation
}

// Insert handler with batch operation - single txid
onInsert: async ({ transaction }) => {
  const items = transaction.mutations.map(m => m.modified)
  const result = await api.todos.createMany({
    data: items
  })
  return { txid: result.txid } // Single txid for batch operation
}

onUpdate()?

optional onUpdate: (params) => Promise<{
  txid: number | number[];
}>;

optional onUpdate: (params) => Promise<{
  txid: number | number[];
}>;

Defined in: packages/electric-db-collection/src/electric.ts:189

Optional asynchronous handler function called before an update operation Must return an object containing a txid number or array of txids

Parameters

params

UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>

Object containing transaction and collection information

Returns

Promise<{ txid: number | number[]; }>

Promise resolving to an object with txid or txids

Examples

// Basic Electric update handler - MUST return { txid: number }
onUpdate: async ({ transaction }) => {
  const { original, changes } = transaction.mutations[0]
  const result = await api.todos.update({
    where: { id: original.id },
    data: changes // Only the changed fields
  })
  return { txid: result.txid } // Required for Electric sync matching
}

// Basic Electric update handler - MUST return { txid: number }
onUpdate: async ({ transaction }) => {
  const { original, changes } = transaction.mutations[0]
  const result = await api.todos.update({
    where: { id: original.id },
    data: changes // Only the changed fields
  })
  return { txid: result.txid } // Required for Electric sync matching
}

// Update handler with multiple items - return array of txids
onUpdate: async ({ transaction }) => {
  const updates = await Promise.all(
    transaction.mutations.map(m =>
      api.todos.update({
        where: { id: m.original.id },
        data: m.changes
      })
    )
  )
  return { txid: updates.map(u => u.txid) } // Array of txids
}

// Update handler with multiple items - return array of txids
onUpdate: async ({ transaction }) => {
  const updates = await Promise.all(
    transaction.mutations.map(m =>
      api.todos.update({
        where: { id: m.original.id },
        data: m.changes
      })
    )
  )
  return { txid: updates.map(u => u.txid) } // Array of txids
}

// Update handler with optimistic rollback
onUpdate: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  try {
    const result = await api.updateTodo(mutation.original.id, mutation.changes)
    return { txid: result.txid }
  } catch (error) {
    // Transaction will automatically rollback optimistic changes
    console.error('Update failed, rolling back:', error)
    throw error
  }
}

// Update handler with optimistic rollback
onUpdate: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  try {
    const result = await api.updateTodo(mutation.original.id, mutation.changes)
    return { txid: result.txid }
  } catch (error) {
    // Transaction will automatically rollback optimistic changes
    console.error('Update failed, rolling back:', error)
    throw error
  }
}

schema?

optional schema: TSchema;

optional schema: TSchema;

Defined in: packages/electric-db-collection/src/electric.ts:89

shapeOptions

shapeOptions: ShapeStreamOptions<GetExtensions<ResolveType<TExplicit, TSchema, TFallback>>>;

shapeOptions: ShapeStreamOptions<GetExtensions<ResolveType<TExplicit, TSchema, TFallback>>>;

Defined in: packages/electric-db-collection/src/electric.ts:81

Configuration options for the ElectricSQL ShapeStream

sync?

optional sync: SyncConfig<ResolveType<TExplicit, TSchema, TFallback>, string | number>;

optional sync: SyncConfig<ResolveType<TExplicit, TSchema, TFallback>, string | number>;

Defined in: packages/electric-db-collection/src/electric.ts:91

ElectricCollectionConfig

Interface: ElectricCollectionConfig<TExplicit, TSchema, TFallback>

Remarks

Type Parameters

Properties

getKey()

Parameters

item

Returns

id?

onDelete()?

Parameters

params

Returns

Examples

onInsert()?

Parameters

params

Returns

Examples

onUpdate()?

Parameters

params

Returns

Examples

schema?

shapeOptions

sync?

Subscribe to Bytes

Subscribe to Bytes