fix: consolidate correctness and reactivity follow-ups

.github/workflows/ci.yml

@@ -6,6 +6,15 @@ on:
   pull_request:
 
 jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run lint
+
   typecheck:
     name: Typecheck
     runs-on: ubuntu-latest

CLAUDE.md

@@ -14,8 +14,8 @@ bun run build
 # Type check
 bun run typecheck
 
-# Run all tests
-bun test
+# Run all tests (everything except tests/browser, which needs a live playground)
+bun run test
 
 # Run a specific test file
 bun test tests/useEntity.test.tsx

eslint.config.mjs

@@ -0,0 +1,33 @@
+import reactHooks from 'eslint-plugin-react-hooks'
+import tsParser from '@typescript-eslint/parser'
+
+// Deliberately narrow: only the React hooks rules. The repo has no lint culture
+// yet, so a broad style ruleset would bury the signal. See PR that added this.
+export default [
+	{
+		ignores: [
+			'**/dist/**',
+			'**/node_modules/**',
+			'**/generated/**',
+			'**/*.d.ts',
+		],
+	},
+	{
+		files: ['packages/*/src/**/*.{ts,tsx}', 'tests/**/*.{ts,tsx}'],
+		languageOptions: {
+			parser: tsParser,
+			ecmaVersion: 2022,
+			sourceType: 'module',
+			parserOptions: {
+				ecmaFeatures: { jsx: true },
+			},
+		},
+		plugins: {
+			'react-hooks': reactHooks,
+		},
+		rules: {
+			'react-hooks/rules-of-hooks': 'error',
+			'react-hooks/exhaustive-deps': 'warn',
+		},
+	},
+]

package.json

@@ -8,9 +8,9 @@
 		"build": "tsc --build",
 		"dev": "tsc --build --watch",
 		"typecheck": "tsc --build",
-		"test": "bun test tests/unit tests/react tests/cases tests/*.test.ts tests/*.test.tsx",
+		"lint": "eslint .",
+		"test": "bun test --path-ignore-patterns='**/tests/browser/**'",
 		"test:browser": "bun test --timeout 30000 tests/browser/",
-		"test:all": "bun test",
 		"playground": "cd packages/example && bun run dev",
 		"playground:contember": "cd packages/example && VITE_CONTEMBER_API_URL=http://localhost:1581 VITE_CONTEMBER_API_TOKEN=0000000000000000000000000000000000000000 bun run dev",
 		"contember:up": "docker compose up -d",
@@ -26,8 +26,11 @@
 		"@testing-library/react": "^16.3.1",
 		"@types/react": "^19",
 		"@types/react-dom": "^19",
+		"@typescript-eslint/parser": "^8.67.0",
 		"@vitejs/plugin-react": "^5.1.2",
 		"bun-types": "^1.3.5",
+		"eslint": "^10.8.1",
+		"eslint-plugin-react-hooks": "^7.1.1",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
 		"typescript": "^5.3.0",

packages/bindx-client/src/graphql/mutationFragments.ts

@@ -76,92 +76,105 @@ export function buildMutationSelection(
 export function buildNodeSelectionFromMutationData(
 	data: Record<string, unknown>,
 ): GraphQlSelectionSet {
-	const fields: GraphQlSelectionSet = [new GraphQlField(null, 'id')]
-
-	for (const [fieldName, value] of Object.entries(data)) {
-		if (value === null || value === undefined) continue
-
-		if (Array.isArray(value)) {
-			const nested = buildSelectionFromOps(value)
-			if (nested) fields.push(new GraphQlField(null, fieldName, {}, nested))
-		} else if (typeof value === 'object') {
-			const nested = buildSelectionFromCreateOrUpdate(value as Record<string, unknown>)
-			if (nested) fields.push(new GraphQlField(null, fieldName, {}, nested))
-		} else {
-			fields.push(new GraphQlField(null, fieldName))
-		}
-	}
+	return buildSelectionFromDataObjects([data])
+}
 
-	return fields
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
 /**
- * Extracts the inner data from a create or update operation and recurses.
+ * Unwraps a create/update/connect operation to the data object whose shape the
+ * response must echo.
+ *
+ * A connect contributes `{ id }` only: the response needs the connected id so a
+ * create op that differs from its sibling solely by what it connects can still be
+ * content-matched against its row.
  */
-function buildSelectionFromCreateOrUpdate(
-	op: Record<string, unknown>,
-): GraphQlSelectionSet | undefined {
-	if ('create' in op && typeof op['create'] === 'object' && op['create'] !== null) {
-		return buildNodeSelectionFromMutationData(op['create'] as Record<string, unknown>)
-	}
-	if ('update' in op && typeof op['update'] === 'object' && op['update'] !== null) {
-		const update = op['update'] as Record<string, unknown>
-		const data = ('data' in update ? update['data'] : update) as Record<string, unknown>
-		return buildNodeSelectionFromMutationData(data)
+function extractOperationData(op: unknown): Record<string, unknown> | undefined {
+	if (!isRecord(op)) return undefined
+
+	const create = op['create']
+	if (isRecord(create)) return create
+
+	const update = op['update']
+	if (isRecord(update)) {
+		// hasMany: `{ update: { by, data } }`; hasOne: `{ update: <data> }`. Both keys are
+		// required to tell them apart — a plain JSON column may be named `data`.
+		const by = update['by']
+		const data = update['data']
+		return isRecord(by) && isRecord(data) ? data : update
 	}
+
+	const connect = op['connect']
+	if (isRecord(connect)) return { id: connect['id'] }
+
 	return undefined
 }
 
 /**
- * Merges selections from all create/update operations in a hasMany array.
- * Collects the union of scalar + relation fields across all operations.
+ * Builds one selection set covering every given data object.
+ *
+ * Sibling ops in a hasMany often carry different subsets of the same relation
+ * (unset fields are absent from create data), so both scalars and nested
+ * relations are unioned — keeping only the last shape would emit a selection
+ * the other siblings' responses cannot be content-matched against.
  */
-function buildSelectionFromOps(ops: unknown[]): GraphQlSelectionSet | undefined {
+function buildSelectionFromDataObjects(
+	dataObjects: readonly Record<string, unknown>[],
+): GraphQlSelectionSet {
 	const scalarFields = new Set<string>()
-	const nestedFields = new Map<string, Record<string, unknown>>()
-	let hasOps = false
+	const nestedOps = new Map<string, unknown[]>()
 
-	for (const item of ops) {
-		if (typeof item !== 'object' || item === null) continue
-		const op = item as Record<string, unknown>
-
-		const innerData =
-			('create' in op && typeof op['create'] === 'object' && op['create'] !== null)
-				? op['create'] as Record<string, unknown>
-				: ('update' in op && typeof op['update'] === 'object' && op['update'] !== null)
-					? (() => { const u = op['update'] as Record<string, unknown>; return ('data' in u ? u['data'] : u) as Record<string, unknown> })()
-					: null
-
-		if (!innerData) continue
-		hasOps = true
+	const collectNested = (fieldName: string, ops: readonly unknown[]): void => {
+		const collected = nestedOps.get(fieldName)
+		if (collected) {
+			collected.push(...ops)
+		} else {
+			nestedOps.set(fieldName, [...ops])
+		}
+	}
 
-		for (const [key, value] of Object.entries(innerData)) {
+	for (const data of dataObjects) {
+		for (const [fieldName, value] of Object.entries(data)) {
 			if (value === null || value === undefined) continue
-			if (typeof value === 'object') {
-				nestedFields.set(key, value as Record<string, unknown>)
-			} else {
-				scalarFields.add(key)
+
+			if (Array.isArray(value)) {
+				collectNested(fieldName, value)
+			} else if (isRecord(value)) {
+				collectNested(fieldName, [value])
+			} else if (fieldName !== 'id') {
+				scalarFields.add(fieldName)
 			}
 		}
 	}
 
-	if (!hasOps) return undefined
-
 	const fields: GraphQlSelectionSet = [new GraphQlField(null, 'id')]
 
 	for (const fieldName of scalarFields) {
 		fields.push(new GraphQlField(null, fieldName))
 	}
 
-	for (const [fieldName, value] of nestedFields) {
-		if (Array.isArray(value)) {
-			const nested = buildSelectionFromOps(value)
-			if (nested) fields.push(new GraphQlField(null, fieldName, {}, nested))
-		} else {
-			const nested = buildSelectionFromCreateOrUpdate(value as Record<string, unknown>)
-			if (nested) fields.push(new GraphQlField(null, fieldName, {}, nested))
-		}
+	for (const [fieldName, ops] of nestedOps) {
+		const nested = buildSelectionFromOps(ops)
+		if (nested) fields.push(new GraphQlField(null, fieldName, {}, nested))
 	}
 
 	return fields
 }
+
+/**
+ * Merges the selections of all create/update operations written to one field.
+ */
+function buildSelectionFromOps(ops: readonly unknown[]): GraphQlSelectionSet | undefined {
+	const dataObjects: Record<string, unknown>[] = []
+
+	for (const op of ops) {
+		const data = extractOperationData(op)
+		if (data) dataObjects.push(data)
+	}
+
+	if (dataObjects.length === 0) return undefined
+
+	return buildSelectionFromDataObjects(dataObjects)
+}

packages/bindx-dataview/src/HasManyDataGrid.tsx

@@ -49,7 +49,6 @@ import { useDataGridSetup } from './useDataGridSetup.js'
 
 export interface HasManyDataGridProps<TEntity extends object = object> {
 	/** Has-many relation field from parent entity */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	field: HasManyRef<TEntity, any>
 	/** Children render function: receives entity proxy `it`, returns column markers + layout */
 	children: (it: EntityAccessor<TEntity>) => ReactNode

packages/bindx-dataview/src/columnLeaf.ts

@@ -97,10 +97,8 @@ export interface ChildrenAnalysisResult {
  */
 export function analyzeChildren(
 	elements: React.ReactNode,
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	markerTypes: ReadonlySet<React.ComponentType<any>>,
 ): ChildrenAnalysisResult {
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	const collected = new Map<React.ComponentType<any>, unknown[]>()
 	for (const type of markerTypes) {
 		collected.set(type, [])
@@ -121,9 +119,7 @@ export function analyzeChildren(
 
 function walkTree(
 	elements: React.ReactNode,
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	markerTypes: ReadonlySet<React.ComponentType<any>>,
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	collected: Map<React.ComponentType<any>, unknown[]>,
 ): void {
 	React.Children.forEach(elements, (child) => {

packages/bindx-dataview/src/columnTypes.ts

@@ -73,6 +73,14 @@ export function accessField(accessor: EntityAccessor<object>, fieldName: string)
 	return current
 }
 
+/**
+ * Access a related entity accessor from a parent row accessor by field name.
+ * EntityAccessor is a Proxy — bracket notation triggers the get trap.
+ */
+export function getRelatedAccessor(item: EntityAccessor<object>, fieldName: string): EntityAccessor<object> | null {
+	return accessField(item, fieldName) as EntityAccessor<object> | null
+}
+
 function extractScalarValue<T>(accessor: EntityAccessor<object>, fieldName: string): T | null {
 	const fieldRef = accessField(accessor, fieldName) as { value?: unknown } | null
 	if (!fieldRef || typeof fieldRef !== 'object') return null

packages/bindx-dataview/src/columns.tsx

@@ -12,8 +12,8 @@
 import React, { ReactNode } from 'react'
 import type { FieldRef, HasOneRef, HasManyRef, FilterHandler, FilterArtifact, EntityAccessor, EnumFilterArtifact, EnumListFilterArtifact, SelectionMeta } from '@contember/bindx'
 import { SelectionScope } from '@contember/bindx'
-import { FIELD_REF_META, createCollectorProxy } from '@contember/bindx-react'
 import { createColumn, createColumnStaticRender, type ColumnRenderProps } from './createColumn.js'
+import { extractFieldName } from './fieldRef.js'
 import { accessField } from './columnTypes.js'
 import { createRelationColumn, hasOneCellConfig, hasManyCellConfig, type RelationColumnProps } from './createRelationColumn.jsx'
 import {
@@ -37,60 +37,6 @@ import { ColumnLeaf, type ColumnLeafProps } from './columnLeaf.js'
 
 export type ColumnMeta = ColumnLeafProps
 
-// ============================================================================
-// Extraction Helpers
-// ============================================================================
-
-interface FieldRefMetaCarrier {
-	readonly [FIELD_REF_META]: {
-		readonly entityType: string
-		readonly fieldName: string
-		readonly fullPath?: readonly string[]
-		readonly isArray: boolean
-		readonly isRelation: boolean
-		readonly enumName?: string
-	}
-}
-
-/** Type guard: checks if a value carries FIELD_REF_META symbol. */
-export function hasFieldRefMeta(ref: unknown): ref is FieldRefMetaCarrier {
-	return ref != null && typeof ref === 'object' && FIELD_REF_META in ref
-}
-
-/**
- * Extract the dotted field path from a field ref (works in both collector and
- * runtime proxies). For fields reached through has-one relations
- * (e.g. `it.author.name`) this is the full dotted path (`"author.name"`) so the
- * DataGrid can build correct nested where/orderBy clauses; for top-level fields
- * it is simply the field name (`"title"`).
- */
-export function extractFieldName(ref: unknown): string | null {
-	if (!hasFieldRefMeta(ref)) return null
-	const meta = ref[FIELD_REF_META]
-	const fullPath = meta.fullPath
-	return fullPath && fullPath.length > 0 ? fullPath.join('.') : meta.fieldName
-}
-
-/** Extract enum name from a field ref (if field is an enum). */
-export function extractEnumName(ref: unknown): string | undefined {
-	return hasFieldRefMeta(ref) ? ref[FIELD_REF_META].enumName : undefined
-}
-
-/** Extract related entity type name from a relation field ref. */
-export function extractRelatedEntityName(ref: unknown): string | null {
-	if (!hasFieldRefMeta(ref)) return null
-	const meta = ref[FIELD_REF_META]
-	return meta.entityType || null
-}
-
-/**
- * Access a related entity accessor from a parent row accessor by field name.
- * EntityAccessor is a Proxy — bracket notation triggers the get trap.
- */
-export function getRelatedAccessor(item: EntityAccessor<object>, fieldName: string): EntityAccessor<object> | null {
-	return accessField(item, fieldName) as EntityAccessor<object> | null
-}
-
 // ============================================================================
 // Default Cell Renderers
 // ============================================================================

packages/bindx-dataview/src/createColumn.ts

@@ -10,7 +10,7 @@ import React from 'react'
 import type { FieldRef, FilterArtifact, FilterHandler, EntityAccessor } from '@contember/bindx'
 import type { ColumnTypeDef } from './columnTypes.js'
 import { ColumnLeaf, type ColumnLeafProps } from './columnLeaf.js'
-import { extractFieldName, extractEnumName } from './columns.js'
+import { extractFieldName, extractEnumName } from './fieldRef.js'
 
 // ============================================================================
 // Render Props