@tanstack/electric-db-collection 0.2.42 → 0.3.0

package/src/electric.ts

@@ -16,15 +16,21 @@ import {
 import { compileSQL } from './sql-compiler'
 import {
   addTagToIndex,
+  deriveDisjunctPositions,
   findRowsMatchingPattern,
   getTagLength,
+  isMoveInMessage,
   isMoveOutMessage,
+  parseTag as parseTagString,
   removeTagFromIndex,
+  rowVisible,
   tagMatchesPattern,
 } from './tag-index'
 import type { ColumnEncoder } from './sql-compiler'
 import type {
-  MoveOutPattern,
+  ActiveConditions,
+  DisjunctPositions,
+  MovePattern,
   MoveTag,
   ParsedMoveTag,
   RowId,
@@ -981,16 +987,16 @@ function createElectricSync<T extends Row<unknown>>(
 
   const tagCache = new Map<MoveTag, ParsedMoveTag>()
 
-  // Parses a tag string into a MoveTag.
+  // Parses a tag string into a ParsedMoveTag.
   // It memoizes the result parsed tag such that future calls
-  // for the same tag string return the same MoveTag array.
+  // for the same tag string return the same ParsedMoveTag array.
   const parseTag = (tag: MoveTag): ParsedMoveTag => {
     const cachedTag = tagCache.get(tag)
     if (cachedTag) {
       return cachedTag
     }
 
-    const parsedTag = tag.split(`|`)
+    const parsedTag = parseTagString(tag)
     tagCache.set(tag, parsedTag)
     return parsedTag
   }
@@ -1000,6 +1006,11 @@ function createElectricSync<T extends Row<unknown>>(
   const tagIndex: TagIndex = []
   let tagLength: number | undefined = undefined
 
+  // DNF state: active_conditions are per-row, disjunct_positions are global
+  // (fixed by the shape's WHERE clause, derived once from the first tagged message).
+  const rowActiveConditions = new Map<RowId, ActiveConditions>()
+  let disjunctPositions: DisjunctPositions | undefined = undefined
+
   /**
    * Initialize the tag index with the correct length
    */
@@ -1074,6 +1085,7 @@ function createElectricSync<T extends Row<unknown>>(
     tags: Array<MoveTag> | undefined,
     removedTags: Array<MoveTag> | undefined,
     rowId: RowId,
+    activeConditions?: ActiveConditions,
   ): Set<MoveTag> => {
     // Initialize tag set for this row if it doesn't exist (needed for checking deletion)
     if (!rowTagSets.has(rowId)) {
@@ -1084,6 +1096,12 @@ function createElectricSync<T extends Row<unknown>>(
     // Add new tags
     if (tags) {
       addTagsToRow(tags, rowId, rowTagSet)
+
+      // Derive disjunct positions once — they are fixed by the shape's WHERE clause.
+      if (disjunctPositions === undefined) {
+        const parsedTags = tags.map(parseTag)
+        disjunctPositions = deriveDisjunctPositions(parsedTags)
+      }
     }
 
     // Remove tags
@@ -1091,6 +1109,11 @@ function createElectricSync<T extends Row<unknown>>(
       removeTagsFromRow(removedTags, rowId, rowTagSet)
     }
 
+    // Store active conditions if provided (overwrite on re-send)
+    if (activeConditions && activeConditions.length > 0) {
+      rowActiveConditions.set(rowId, [...activeConditions])
+    }
+
     return rowTagSet
   }
 
@@ -1101,6 +1124,8 @@ function createElectricSync<T extends Row<unknown>>(
     rowTagSets.clear()
     tagIndex.length = 0
     tagLength = undefined
+    rowActiveConditions.clear()
+    disjunctPositions = undefined
   }
 
   /**
@@ -1129,22 +1154,45 @@ function createElectricSync<T extends Row<unknown>>(
 
     // Remove the row from the tag sets map
     rowTagSets.delete(rowId)
+    rowActiveConditions.delete(rowId)
   }
 
   /**
    * Remove matching tags from a row based on a pattern
-   * Returns true if the row's tag set is now empty
+   * Returns true if the row should be deleted (no longer visible)
    */
   const removeMatchingTagsFromRow = (
     rowId: RowId,
-    pattern: MoveOutPattern,
+    pattern: MovePattern,
   ): boolean => {
     const rowTagSet = rowTagSets.get(rowId)
     if (!rowTagSet) {
       return false
     }
 
-    // Find tags that match this pattern and remove them
+    // DNF mode: check visibility using active conditions.
+    // Tag index entries are preserved so that move-in can re-activate positions.
+    const activeConditions = rowActiveConditions.get(rowId)
+    if (activeConditions && disjunctPositions) {
+      // Set the condition at this pattern's position to false
+      activeConditions[pattern.pos] = false
+
+      if (!rowVisible(activeConditions, disjunctPositions)) {
+        // Row is no longer visible — clean up all state including tag index
+        for (const tag of rowTagSet) {
+          const parsedTag = parseTag(tag)
+          removeTagFromIndex(parsedTag, rowId, tagIndex, tagLength!)
+          tagCache.delete(tag)
+        }
+        rowTagSets.delete(rowId)
+        rowActiveConditions.delete(rowId)
+        return true
+      }
+      return false
+    }
+
+    // Simple shape (no subquery dependencies — server sends no active_conditions):
+    // Remove matching tags and delete if tag set is empty
     for (const tag of rowTagSet) {
       const parsedTag = parseTag(tag)
       if (tagMatchesPattern(parsedTag, pattern)) {
@@ -1153,7 +1201,6 @@ function createElectricSync<T extends Row<unknown>>(
       }
     }
 
-    // Check if row's tag set is now empty
     if (rowTagSet.size === 0) {
       rowTagSets.delete(rowId)
       return true
@@ -1166,7 +1213,7 @@ function createElectricSync<T extends Row<unknown>>(
    * Process move-out event: remove matching tags from rows and delete rows with empty tag sets
    */
   const processMoveOutEvent = (
-    patterns: Array<MoveOutPattern>,
+    patterns: Array<MovePattern>,
     begin: () => void,
     write: (message: ChangeMessageOrDeleteKeyMessage<T>) => void,
     transactionStarted: boolean,
@@ -1204,6 +1251,30 @@ function createElectricSync<T extends Row<unknown>>(
     return txStarted
   }
 
+  /**
+   * Process move-in event: re-activate conditions for rows matching the patterns.
+   * This is a silent operation — no messages are emitted to the collection.
+   */
+  const processMoveInEvent = (patterns: Array<MovePattern>): void => {
+    if (tagLength === undefined) {
+      debug(
+        `${collectionId ? `[${collectionId}] ` : ``}Received move-in message but no tag length set yet, ignoring`,
+      )
+      return
+    }
+
+    for (const pattern of patterns) {
+      const affectedRowIds = findRowsMatchingPattern(pattern, tagIndex)
+
+      for (const rowId of affectedRowIds) {
+        const activeConditions = rowActiveConditions.get(rowId)
+        if (activeConditions) {
+          activeConditions[pattern.pos] = true
+        }
+      }
+    }
+  }
+
   /**
    * Get the sync metadata for insert operations
    * @returns Record containing relation information
@@ -1433,6 +1504,11 @@ function createElectricSync<T extends Row<unknown>>(
         const removedTags = changeMessage.headers.removed_tags
         const hasTags = tags || removedTags
 
+        // Extract active_conditions from headers (DNF support)
+        const activeConditions = changeMessage.headers.active_conditions as
+          | ActiveConditions
+          | undefined
+
         const rowId = collection.getKeyFromItem(changeMessage.value)
         const operation = changeMessage.headers.operation
 
@@ -1453,7 +1529,12 @@ function createElectricSync<T extends Row<unknown>>(
         if (isDelete) {
           clearTagsForRow(rowId)
         } else if (hasTags) {
-          processTagsForChangeMessage(tags, removedTags, rowId)
+          processTagsForChangeMessage(
+            tags,
+            removedTags,
+            rowId,
+            activeConditions,
+          )
         }
 
         write({
@@ -1496,7 +1577,11 @@ function createElectricSync<T extends Row<unknown>>(
 
         for (const message of messages) {
           // Add message to current batch buffer (for race condition handling)
-          if (isChangeMessage(message) || isMoveOutMessage(message)) {
+          if (
+            isChangeMessage(message) ||
+            isMoveOutMessage(message) ||
+            isMoveInMessage(message)
+          ) {
             currentBatchMessages.setState((currentBuffer) => {
               const newBuffer = [...currentBuffer, message]
               // Limit buffer size for safety
@@ -1593,6 +1678,14 @@ function createElectricSync<T extends Row<unknown>>(
                 transactionStarted,
               )
             }
+          } else if (isMoveInMessage(message)) {
+            // Handle move-in event: re-activate conditions for matching rows.
+            // Buffer if buffering, otherwise process immediately.
+            if (isBufferingInitialSync() && !transactionStarted) {
+              bufferedMessages.push(message)
+            } else {
+              processMoveInEvent(message.headers.patterns)
+            }
           } else if (isMustRefetchMessage(message)) {
             debug(
               `${collectionId ? `[${collectionId}] ` : ``}Received must-refetch message, starting transaction with truncate`,
@@ -1672,6 +1765,9 @@ function createElectricSync<T extends Row<unknown>>(
                   write,
                   transactionStarted,
                 )
+              } else if (isMoveInMessage(bufferedMsg)) {
+                // Process buffered move-in messages during atomic swap
+                processMoveInEvent(bufferedMsg.headers.patterns)
               }
             }
 

package/src/tag-index.ts

@@ -3,23 +3,32 @@ import type { Message, Row } from '@electric-sql/client'
 
 export type RowId = string | number
 export type MoveTag = string
-export type ParsedMoveTag = Array<string>
+export type ParsedMoveTag = Array<string | NonParticipating>
 export type Position = number
 export type Value = string
-export type MoveOutPattern = {
+export type MovePattern = {
   pos: Position
   value: Value
 }
 
-const TAG_WILDCARD = `_`
+/**
+ * Sentinel value for tag positions where the disjunct does not participate
+ * in that condition. These positions are not indexed and won't match any
+ * move pattern.
+ */
+export const NON_PARTICIPATING = null
+export type NonParticipating = typeof NON_PARTICIPATING
+
+export type ActiveConditions = Array<boolean>
+export type DisjunctPositions = Array<Array<number>>
 
 /**
- * Event message type for move-out events
+ * Event message type for move-out and move-in events
  */
 export interface EventMessage {
   headers: {
-    event: `move-out`
-    patterns: Array<MoveOutPattern>
+    event: `move-out` | `move-in`
+    patterns: Array<MovePattern>
   }
 }
 
@@ -41,10 +50,21 @@ export interface EventMessage {
  */
 export type TagIndex = Array<Map<Value, Set<RowId>>>
 
+/**
+ * Parse a tag string into a ParsedMoveTag.
+ * Splits on `/` delimiter and maps empty strings to {@link NON_PARTICIPATING}.
+ */
+export function parseTag(tag: MoveTag): ParsedMoveTag {
+  return tag.split(`/`).map((s) => (s === `` ? NON_PARTICIPATING : s))
+}
+
 /**
  * Abstraction to get the value at a specific position in a tag
  */
-export function getValue(tag: ParsedMoveTag, position: Position): Value {
+export function getValue(
+  tag: ParsedMoveTag,
+  position: Position,
+): string | NonParticipating {
   if (position >= tag.length) {
     throw new Error(`Position out of bounds`)
   }
@@ -54,7 +74,7 @@ export function getValue(tag: ParsedMoveTag, position: Position): Value {
 /**
  * Abstraction to extract position and value from a pattern.
  */
-function getPositionalValue(pattern: MoveOutPattern): {
+function getPositionalValue(pattern: MovePattern): {
   pos: number
   value: string
 } {
@@ -70,16 +90,16 @@ export function getTagLength(tag: ParsedMoveTag): number {
 
 /**
  * Check if a tag matches a pattern.
- * A tag matches if the value at the pattern's position equals the pattern's value,
- * or if the value at that position is "_" (wildcard).
+ * A tag matches if the value at the pattern's position equals the pattern's value.
+ * {@link NON_PARTICIPATING} positions naturally don't match any string value.
  */
 export function tagMatchesPattern(
   tag: ParsedMoveTag,
-  pattern: MoveOutPattern,
+  pattern: MovePattern,
 ): boolean {
   const { pos, value } = getPositionalValue(pattern)
   const tagValue = getValue(tag, pos)
-  return tagValue === value || tagValue === TAG_WILDCARD
+  return tagValue === value
 }
 
 /**
@@ -94,8 +114,7 @@ export function addTagToIndex(
   for (let i = 0; i < tagLength; i++) {
     const value = getValue(tag, i)
 
-    // Only index non-wildcard values
-    if (value !== TAG_WILDCARD) {
+    if (value !== NON_PARTICIPATING) {
       const positionIndex = index[i]!
       if (!positionIndex.has(value)) {
         positionIndex.set(value, new Set())
@@ -119,8 +138,7 @@ export function removeTagFromIndex(
   for (let i = 0; i < tagLength; i++) {
     const value = getValue(tag, i)
 
-    // Only remove non-wildcard values
-    if (value !== TAG_WILDCARD) {
+    if (value !== NON_PARTICIPATING) {
       const positionIndex = index[i]
       if (positionIndex) {
         const rowSet = positionIndex.get(value)
@@ -141,7 +159,7 @@ export function removeTagFromIndex(
  * Find all rows that match a given pattern
  */
 export function findRowsMatchingPattern(
-  pattern: MoveOutPattern,
+  pattern: MovePattern,
   index: TagIndex,
 ): Set<RowId> {
   const { pos, value } = getPositionalValue(pattern)
@@ -150,6 +168,38 @@ export function findRowsMatchingPattern(
   return rowSet ?? new Set()
 }
 
+/**
+ * Derive disjunct positions from parsed tags.
+ * For each tag (= disjunct), collect the indices of participating positions.
+ * E.g., ["hash_a", NON_PARTICIPATING, "hash_b"] → [0, 2]
+ */
+export function deriveDisjunctPositions(
+  tags: Array<ParsedMoveTag>,
+): DisjunctPositions {
+  return tags.map((tag) => {
+    const positions: Array<number> = []
+    for (let i = 0; i < tag.length; i++) {
+      if (tag[i] !== NON_PARTICIPATING) {
+        positions.push(i)
+      }
+    }
+    return positions
+  })
+}
+
+/**
+ * Evaluate whether a row is visible given active conditions and disjunct positions.
+ * Returns true if ANY disjunct has ALL its positions as true in activeConditions.
+ */
+export function rowVisible(
+  activeConditions: ActiveConditions,
+  disjunctPositions: DisjunctPositions,
+): boolean {
+  return disjunctPositions.some((positions) =>
+    positions.every((pos) => activeConditions[pos]),
+  )
+}
+
 /**
  * Check if a message is an event message with move-out event
  */
@@ -158,3 +208,12 @@ export function isMoveOutMessage<T extends Row<unknown>>(
 ): message is Message<T> & EventMessage {
   return message.headers.event === `move-out`
 }
+
+/**
+ * Check if a message is an event message with move-in event
+ */
+export function isMoveInMessage<T extends Row<unknown>>(
+  message: Message<T>,
+): message is Message<T> & EventMessage {
+  return message.headers.event === `move-in`
+}