Interface: ElectricCollectionConfig<T, TSchema>

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

Configuration interface for Electric collection options

Extends

Omit<BaseCollectionConfig<T, string | number, TSchema, UtilsRecord, any>, "onInsert" | "onUpdate" | "onDelete" | "syncMode">

Type Parameters

T

T extends Row<unknown> = Row<unknown>

The type of items in the collection

TSchema

TSchema extends StandardSchemaV1 = never

The schema type for validation

Properties

[ELECTRIC_TEST_HOOKS]?

optional [ELECTRIC_TEST_HOOKS]: ElectricTestHooks;

optional [ELECTRIC_TEST_HOOKS]: ElectricTestHooks;

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

Internal test hooks (for testing only) Hidden via Symbol to prevent accidental usage in production

onDelete()?

optional onDelete: (params) => Promise<MatchingStrategy>;

optional onDelete: (params) => Promise<MatchingStrategy>;

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

Optional asynchronous handler function called before a delete operation

Parameters

params

DeleteMutationFnParams<T>

Object containing transaction and collection information

Returns

Promise<MatchingStrategy>

Promise resolving to { txid, timeout? } or void

Examples

// Basic Electric delete handler with txid (recommended)
onDelete: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  const result = await api.todos.delete({
    id: mutation.original.id
  })
  return { txid: result.txid }
}

// Basic Electric delete handler with txid (recommended)
onDelete: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  const result = await api.todos.delete({
    id: mutation.original.id
  })
  return { txid: result.txid }
}

// Use awaitMatch utility for custom matching
onDelete: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.todos.delete({ id: mutation.original.id })
  await collection.utils.awaitMatch(
    (message) => isChangeMessage(message) &&
                 message.headers.operation === 'delete' &&
                 message.value.id === mutation.original.id
  )
}

// Use awaitMatch utility for custom matching
onDelete: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.todos.delete({ id: mutation.original.id })
  await collection.utils.awaitMatch(
    (message) => isChangeMessage(message) &&
                 message.headers.operation === 'delete' &&
                 message.value.id === mutation.original.id
  )
}

onInsert()?

optional onInsert: (params) => Promise<MatchingStrategy>;

optional onInsert: (params) => Promise<MatchingStrategy>;

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

Optional asynchronous handler function called before an insert operation

Parameters

params

InsertMutationFnParams<T>

Object containing transaction and collection information

Returns

Promise<MatchingStrategy>

Promise resolving to { txid, timeout? } or void

Examples

// Basic Electric insert handler with txid (recommended)
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  const result = await api.todos.create({
    data: newItem
  })
  return { txid: result.txid }
}

// Basic Electric insert handler with txid (recommended)
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  const result = await api.todos.create({
    data: newItem
  })
  return { txid: result.txid }
}

// Insert handler with custom timeout
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  const result = await api.todos.create({
    data: newItem
  })
  return { txid: result.txid, timeout: 10000 } // Wait up to 10 seconds
}

// Insert handler with custom timeout
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  const result = await api.todos.create({
    data: newItem
  })
  return { txid: result.txid, timeout: 10000 } // Wait up to 10 seconds
}

// 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) }
}

// 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) }
}

// Use awaitMatch utility for custom matching
onInsert: async ({ transaction, collection }) => {
  const newItem = transaction.mutations[0].modified
  await api.todos.create({ data: newItem })
  await collection.utils.awaitMatch(
    (message) => isChangeMessage(message) &&
                 message.headers.operation === 'insert' &&
                 message.value.name === newItem.name
  )
}

// Use awaitMatch utility for custom matching
onInsert: async ({ transaction, collection }) => {
  const newItem = transaction.mutations[0].modified
  await api.todos.create({ data: newItem })
  await collection.utils.awaitMatch(
    (message) => isChangeMessage(message) &&
                 message.headers.operation === 'insert' &&
                 message.value.name === newItem.name
  )
}

onUpdate()?

optional onUpdate: (params) => Promise<MatchingStrategy>;

optional onUpdate: (params) => Promise<MatchingStrategy>;

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

Optional asynchronous handler function called before an update operation

Parameters

params

UpdateMutationFnParams<T>

Object containing transaction and collection information

Returns

Promise<MatchingStrategy>

Promise resolving to { txid, timeout? } or void

Examples

// Basic Electric update handler with txid (recommended)
onUpdate: async ({ transaction }) => {
  const { original, changes } = transaction.mutations[0]
  const result = await api.todos.update({
    where: { id: original.id },
    data: changes
  })
  return { txid: result.txid }
}

// Basic Electric update handler with txid (recommended)
onUpdate: async ({ transaction }) => {
  const { original, changes } = transaction.mutations[0]
  const result = await api.todos.update({
    where: { id: original.id },
    data: changes
  })
  return { txid: result.txid }
}

// Use awaitMatch utility for custom matching
onUpdate: async ({ transaction, collection }) => {
  const { original, changes } = transaction.mutations[0]
  await api.todos.update({ where: { id: original.id }, data: changes })
  await collection.utils.awaitMatch(
    (message) => isChangeMessage(message) &&
                 message.headers.operation === 'update' &&
                 message.value.id === original.id
  )
}

// Use awaitMatch utility for custom matching
onUpdate: async ({ transaction, collection }) => {
  const { original, changes } = transaction.mutations[0]
  await api.todos.update({ where: { id: original.id }, data: changes })
  await collection.utils.awaitMatch(
    (message) => isChangeMessage(message) &&
                 message.headers.operation === 'update' &&
                 message.value.id === original.id
  )
}

shapeOptions

shapeOptions: ShapeStreamOptions<GetExtensions<T>>;

shapeOptions: ShapeStreamOptions<GetExtensions<T>>;

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

Configuration options for the ElectricSQL ShapeStream

syncMode?

optional syncMode: ElectricSyncMode;

optional syncMode: ElectricSyncMode;

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