E2E Test Suite for Query-Driven Sync

.github/workflows/e2e-tests.yml

@@ -0,0 +1,77 @@
+name: E2E Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  e2e-tests:
+    name: Run E2E Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.19.0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Start Docker services
+        run: |
+          cd packages/db-collection-e2e/docker
+          docker compose up -d
+          echo "Waiting for services to be healthy..."
+          timeout 60 bash -c 'until docker compose ps | grep -q "healthy"; do sleep 2; done'
+
+      - name: Build packages
+        run: |
+          pnpm --filter @tanstack/db-ivm build
+          pnpm --filter @tanstack/db build
+          pnpm --filter @tanstack/electric-db-collection build
+          pnpm --filter @tanstack/query-db-collection build
+
+      - name: Run Electric E2E tests
+        run: |
+          cd packages/electric-db-collection
+          pnpm test:e2e
+        env:
+          ELECTRIC_URL: http://localhost:3000
+          POSTGRES_HOST: localhost
+          POSTGRES_PORT: 54321
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: password
+          POSTGRES_DB: e2e_test
+
+      - name: Run Query E2E tests
+        run: |
+          cd packages/query-db-collection
+          pnpm test:e2e
+        env:
+          ELECTRIC_URL: http://localhost:3000
+
+      - name: Stop Docker services
+        if: always()
+        run: |
+          cd packages/db-collection-e2e/docker
+          docker compose down -v
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: packages/db-collection-e2e/junit/
+          retention-days: 7

docs/reference/functions/createCollection.md

@@ -39,7 +39,7 @@ The utilities record type
 
 #### options
 
-[`CollectionConfig`](../../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, [`UtilsRecord`](../../type-aliases/UtilsRecord.md)\> & `object` & [`NonSingleResult`](../../type-aliases/NonSingleResult.md)
+[`CollectionConfig`](../../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, `TUtils`\> & `object` & [`NonSingleResult`](../../type-aliases/NonSingleResult.md)
 
 Collection options with optional utilities
 
@@ -148,7 +148,7 @@ The utilities record type
 
 #### options
 
-[`CollectionConfig`](../../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, [`UtilsRecord`](../../type-aliases/UtilsRecord.md)\> & `object` & [`SingleResult`](../../type-aliases/SingleResult.md)
+[`CollectionConfig`](../../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, `TUtils`\> & `object` & [`SingleResult`](../../type-aliases/SingleResult.md)
 
 Collection options with optional utilities
 
@@ -257,7 +257,7 @@ The utilities record type
 
 #### options
 
-[`CollectionConfig`](../../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, [`UtilsRecord`](../../type-aliases/UtilsRecord.md)\> & `object` & [`NonSingleResult`](../../type-aliases/NonSingleResult.md)
+[`CollectionConfig`](../../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, `TUtils`\> & `object` & [`NonSingleResult`](../../type-aliases/NonSingleResult.md)
 
 Collection options with optional utilities
 
@@ -366,7 +366,7 @@ The utilities record type
 
 #### options
 
-[`CollectionConfig`](../../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, [`UtilsRecord`](../../type-aliases/UtilsRecord.md)\> & `object` & [`SingleResult`](../../type-aliases/SingleResult.md)
+[`CollectionConfig`](../../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, `TUtils`\> & `object` & [`SingleResult`](../../type-aliases/SingleResult.md)
 
 Collection options with optional utilities
 

docs/reference/functions/extractSimpleComparisons.md

@@ -9,13 +9,15 @@ title: extractSimpleComparisons
 function extractSimpleComparisons(expr): SimpleComparison[];
 ```
 
-Defined in: [packages/db/src/query/expression-helpers.ts:323](https://github.com/TanStack/db/blob/main/packages/db/src/query/expression-helpers.ts#L323)
+Defined in: [packages/db/src/query/expression-helpers.ts:327](https://github.com/TanStack/db/blob/main/packages/db/src/query/expression-helpers.ts#L327)
 
 Extracts all simple comparisons from a WHERE expression.
 This is useful for simple APIs that only support basic filters.
 
-Note: This only works for simple AND-ed conditions. Throws an error if it encounters
-unsupported operations like OR, NOT, or complex nested expressions.
+Note: This only works for simple AND-ed conditions and NOT-wrapped comparisons.
+Throws an error if it encounters unsupported operations like OR or complex nested expressions.
+
+NOT operators are flattened by prefixing the operator name (e.g., `not(eq(...))` becomes `not_eq`).
 
 ## Parameters
 
@@ -33,14 +35,16 @@ Array of simple comparisons
 
 ## Throws
 
-Error if expression contains OR, NOT, or other unsupported operations
+Error if expression contains OR or other unsupported operations
 
 ## Example
 
 ```typescript
 const comparisons = extractSimpleComparisons(where)
 // Returns: [
 //   { field: ['category'], operator: 'eq', value: 'electronics' },
-//   { field: ['price'], operator: 'lt', value: 100 }
+//   { field: ['price'], operator: 'lt', value: 100 },
+//   { field: ['email'], operator: 'isNull' }, // No value for null checks
+//   { field: ['status'], operator: 'not_eq', value: 'archived' }
 // ]
 ```

docs/reference/functions/localStorageCollectionOptions.md

@@ -8,7 +8,7 @@ title: localStorageCollectionOptions
 ## Call Signature
 
 ```ts
-function localStorageCollectionOptions<T, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, UtilsRecord> & object;
+function localStorageCollectionOptions<T, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, LocalStorageCollectionUtils> & object;
 ```
 
 Defined in: [packages/db/src/local-storage.ts:279](https://github.com/TanStack/db/blob/main/packages/db/src/local-storage.ts#L279)
@@ -52,7 +52,7 @@ Configuration options for the localStorage collection
 
 ### Returns
 
-[`CollectionConfig`](../../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, [`UtilsRecord`](../../type-aliases/UtilsRecord.md)\> & `object`
+[`CollectionConfig`](../../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, [`LocalStorageCollectionUtils`](../../interfaces/LocalStorageCollectionUtils.md)\> & `object`
 
 Collection options with utilities including clearStorage, getStorageSize, and acceptMutations
 
@@ -123,10 +123,10 @@ await tx.commit()
 ## Call Signature
 
 ```ts
-function localStorageCollectionOptions<T, TKey>(config): CollectionConfig<T, TKey, never, UtilsRecord> & object;
+function localStorageCollectionOptions<T, TKey>(config): CollectionConfig<T, TKey, never, LocalStorageCollectionUtils> & object;
 ```
 
-Defined in: [packages/db/src/local-storage.ts:294](https://github.com/TanStack/db/blob/main/packages/db/src/local-storage.ts#L294)
+Defined in: [packages/db/src/local-storage.ts:299](https://github.com/TanStack/db/blob/main/packages/db/src/local-storage.ts#L299)
 
 Creates localStorage collection options for use with a standard Collection
 
@@ -167,7 +167,7 @@ Configuration options for the localStorage collection
 
 ### Returns
 
-[`CollectionConfig`](../../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, [`UtilsRecord`](../../type-aliases/UtilsRecord.md)\> & `object`
+[`CollectionConfig`](../../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, [`LocalStorageCollectionUtils`](../../interfaces/LocalStorageCollectionUtils.md)\> & `object`
 
 Collection options with utilities including clearStorage, getStorageSize, and acceptMutations
 

docs/reference/functions/parseLoadSubsetOptions.md

@@ -9,7 +9,7 @@ title: parseLoadSubsetOptions
 function parseLoadSubsetOptions(options): object;
 ```
 
-Defined in: [packages/db/src/query/expression-helpers.ts:420](https://github.com/TanStack/db/blob/main/packages/db/src/query/expression-helpers.ts#L420)
+Defined in: [packages/db/src/query/expression-helpers.ts:499](https://github.com/TanStack/db/blob/main/packages/db/src/query/expression-helpers.ts#L499)
 
 Convenience function to get all LoadSubsetOptions in a pre-parsed format.
 Good starting point for simple use cases.

docs/reference/interfaces/SimpleComparison.md

@@ -31,10 +31,10 @@ Defined in: [packages/db/src/query/expression-helpers.ts:46](https://github.com/
 
 ***
 
-### value
+### value?
 
 ```ts
-value: any;
+optional value: any;
 ```
 
 Defined in: [packages/db/src/query/expression-helpers.ts:47](https://github.com/TanStack/db/blob/main/packages/db/src/query/expression-helpers.ts#L47)