@contember/bindx 0.1.0

package/src/selection/SelectionMetaCollector.ts

@@ -0,0 +1,122 @@
+import type { SelectionMeta, SelectionFieldMeta } from './types.js'
+import { generateHasManyAlias } from '../utils/aliasGenerator.js'
+
+/**
+ * Class for collecting field selection metadata during collection phase
+ */
+export class SelectionMetaCollector implements SelectionMeta {
+	readonly fields = new Map<string, SelectionFieldMeta>()
+
+	/**
+	 * Add a field to the selection.
+	 *
+	 * For has-many fields with parameters (filter, orderBy, limit, offset),
+	 * uses alias as the key to allow multiple instances of the same field
+	 * with different parameters.
+	 */
+	addField(fieldMeta: SelectionFieldMeta): void {
+		let key: string
+
+		// For has-many fields with parameters, use alias as the key
+		// This allows multiple HasMany for the same field with different params
+		if (fieldMeta.isArray && fieldMeta.hasManyParams) {
+			const hasParams = fieldMeta.hasManyParams.filter !== undefined ||
+				fieldMeta.hasManyParams.orderBy !== undefined ||
+				fieldMeta.hasManyParams.limit !== undefined ||
+				fieldMeta.hasManyParams.offset !== undefined
+
+			if (hasParams) {
+				// Generate auto-alias if alias equals fieldName
+				if (fieldMeta.alias === fieldMeta.fieldName) {
+					fieldMeta.alias = generateHasManyAlias(fieldMeta.fieldName, fieldMeta.hasManyParams)
+				}
+				// Use alias-based key for has-many with params
+				const pathWithAlias = [...fieldMeta.path.slice(0, -1), fieldMeta.alias]
+				key = pathWithAlias.join('.')
+			} else {
+				key = fieldMeta.path.join('.')
+			}
+		} else {
+			key = fieldMeta.path.join('.')
+		}
+
+		const existing = this.fields.get(key)
+
+		if (existing) {
+			// Update relation/array flags if source has more specific info
+			if (fieldMeta.isRelation && !existing.isRelation) {
+				existing.isRelation = true
+			}
+			if (fieldMeta.isArray && !existing.isArray) {
+				existing.isArray = true
+			}
+			// Merge nested selections if both have them
+			if (fieldMeta.nested && existing.nested) {
+				mergeSelections(existing.nested, fieldMeta.nested)
+			} else if (fieldMeta.nested) {
+				existing.nested = fieldMeta.nested
+			}
+		} else {
+			this.fields.set(key, { ...fieldMeta })
+		}
+	}
+
+	/**
+	 * Get all root-level fields (not nested)
+	 */
+	getRootFields(): SelectionFieldMeta[] {
+		const result: SelectionFieldMeta[] = []
+		for (const field of this.fields.values()) {
+			if (field.path.length === 1) {
+				result.push(field)
+			}
+		}
+		return result
+	}
+
+	/**
+	 * Convert to plain object for serialization
+	 */
+	toJSON(): SelectionMeta {
+		return {
+			fields: new Map(this.fields),
+		}
+	}
+}
+
+/**
+ * Merge two selections together
+ */
+export function mergeSelections(target: SelectionMeta, source: SelectionMeta): void {
+	for (const [key, field] of source.fields) {
+		const existing = target.fields.get(key)
+		if (existing) {
+			// Update relation/array flags if source has more specific info
+			if (field.isRelation && !existing.isRelation) {
+				existing.isRelation = true
+			}
+			if (field.isArray && !existing.isArray) {
+				existing.isArray = true
+			}
+			// Merge hasManyParams if source has them
+			if (field.hasManyParams && !existing.hasManyParams) {
+				existing.hasManyParams = field.hasManyParams
+			}
+			// Merge nested selections
+			if (field.nested && existing.nested) {
+				mergeSelections(existing.nested, field.nested)
+			} else if (field.nested) {
+				existing.nested = field.nested
+			}
+		} else {
+			target.fields.set(key, { ...field })
+		}
+	}
+}
+
+/**
+ * Create empty selection metadata
+ */
+export function createEmptySelection(): SelectionMeta {
+	return { fields: new Map() }
+}

package/src/selection/SelectionScope.ts

@@ -0,0 +1,208 @@
+import type { SelectionMeta, SelectionFieldMeta } from './types.js'
+import { generateHasManyAlias } from '../utils/aliasGenerator.js'
+
+/**
+ * HasMany parameters for filtering, ordering, pagination
+ */
+export interface HasManyParams {
+	filter?: unknown
+	orderBy?: unknown
+	limit?: number
+	offset?: number
+	totalCount?: boolean
+}
+
+/**
+ * Relation metadata stored at parent level
+ */
+interface RelationMeta {
+	isArray: boolean
+	params?: HasManyParams
+}
+
+/**
+ * Tree-based selection scope for collecting field selections.
+ *
+ * Unlike the flat path-based SelectionMetaCollector, SelectionScope
+ * maintains a hierarchical tree structure that naturally represents
+ * nested entity selections.
+ *
+ * Key benefits:
+ * - Natural tree structure matches entity relationships
+ * - No path string manipulation or collision risks
+ * - Scope carries its context - no need for symbol passing
+ * - Simple merge: just combine tree nodes
+ */
+export class SelectionScope {
+	// Tree structure
+	private parent: SelectionScope | null = null
+	private children: Map<string, SelectionScope> = new Map()
+
+	// Fields at this level
+	private scalarFields: Set<string> = new Set()
+	private relationMeta: Map<string, RelationMeta> = new Map()
+
+	/**
+	 * Create or get a child scope for a relation field.
+	 * Automatically removes the field from scalars if it was there.
+	 * New child scopes always include 'id' as a minimum selection.
+	 */
+	child(fieldName: string): SelectionScope {
+		// Remove from scalars if it was added as scalar first
+		this.scalarFields.delete(fieldName)
+
+		let childScope = this.children.get(fieldName)
+		if (!childScope) {
+			childScope = new SelectionScope()
+			childScope.parent = this
+			childScope.addScalar('id')
+			this.children.set(fieldName, childScope)
+			this.relationMeta.set(fieldName, { isArray: false })
+		}
+		return childScope
+	}
+
+	/**
+	 * Add a scalar field to this scope.
+	 * If the field is already a relation, this is a no-op.
+	 */
+	addScalar(fieldName: string): void {
+		if (!this.children.has(fieldName)) {
+			this.scalarFields.add(fieldName)
+		}
+	}
+
+	/**
+	 * Mark a relation field as array (hasMany).
+	 */
+	markAsArray(fieldName: string): void {
+		const meta = this.relationMeta.get(fieldName)
+		if (meta) {
+			meta.isArray = true
+		}
+	}
+
+	/**
+	 * Set hasMany parameters for a relation field.
+	 */
+	setHasManyParams(fieldName: string, params: HasManyParams): void {
+		const meta = this.relationMeta.get(fieldName)
+		if (meta) {
+			meta.params = params
+		}
+	}
+
+	/**
+	 * Check if this scope has any fields (scalar or relation).
+	 */
+	hasFields(): boolean {
+		return this.scalarFields.size > 0 || this.children.size > 0
+	}
+
+	/**
+	 * Merge another scope into this one.
+	 * Scalar fields are added, relation children are recursively merged.
+	 */
+	merge(other: SelectionScope): void {
+		// Merge scalar fields
+		for (const field of other.scalarFields) {
+			this.addScalar(field)
+		}
+
+		// Merge relation children
+		for (const [fieldName, otherChild] of other.children) {
+			const thisChild = this.child(fieldName)
+			thisChild.merge(otherChild)
+
+			// Merge relation metadata
+			const otherMeta = other.relationMeta.get(fieldName)
+			if (otherMeta) {
+				const thisMeta = this.relationMeta.get(fieldName)!
+				if (otherMeta.isArray) {
+					thisMeta.isArray = true
+				}
+				if (otherMeta.params && !thisMeta.params) {
+					thisMeta.params = otherMeta.params
+				}
+			}
+		}
+	}
+
+	/**
+	 * Merge fields from a SelectionMeta into this scope.
+	 * Useful for integrating with existing fluent builder selections.
+	 */
+	mergeFromSelectionMeta(meta: SelectionMeta): void {
+		for (const [_key, field] of meta.fields) {
+			// Only process root-level fields
+			if (field.path.length !== 1) continue
+
+			if (field.isRelation && field.nested) {
+				const childScope = this.child(field.fieldName)
+				if (field.isArray) {
+					this.markAsArray(field.fieldName)
+				}
+				if (field.hasManyParams) {
+					this.setHasManyParams(field.fieldName, field.hasManyParams)
+				}
+				childScope.mergeFromSelectionMeta(field.nested)
+			} else {
+				this.addScalar(field.fieldName)
+			}
+		}
+	}
+
+	/**
+	 * Convert this scope to SelectionMeta format for backwards compatibility.
+	 * This allows the new SelectionScope to be used with existing query builders.
+	 *
+	 * For has-many fields with params, generates auto-alias to allow multiple
+	 * HasMany components for the same field with different parameters.
+	 */
+	toSelectionMeta(): SelectionMeta {
+		const fields = new Map<string, SelectionFieldMeta>()
+
+		// Add scalar fields
+		for (const fieldName of this.scalarFields) {
+			fields.set(fieldName, {
+				fieldName,
+				alias: fieldName,
+				path: [fieldName],
+				isRelation: false,
+				isArray: false,
+			})
+		}
+
+		// Add relation fields with nested selections
+		for (const [fieldName, childScope] of this.children) {
+			const meta = this.relationMeta.get(fieldName)!
+
+			// Generate alias for has-many fields with params
+			const alias = meta.isArray && meta.params
+				? generateHasManyAlias(fieldName, meta.params)
+				: fieldName
+
+			fields.set(alias, {
+				fieldName,
+				alias,
+				path: [fieldName],
+				isRelation: true,
+				isArray: meta.isArray,
+				nested: childScope.toSelectionMeta(),
+				hasManyParams: meta.params,
+			})
+		}
+
+		return { fields }
+	}
+
+	/**
+	 * Create a SelectionScope from an existing SelectionMeta.
+	 * Useful for converting explicit selections to scope format.
+	 */
+	static fromSelectionMeta(meta: SelectionMeta): SelectionScope {
+		const scope = new SelectionScope()
+		scope.mergeFromSelectionMeta(meta)
+		return scope
+	}
+}

package/src/selection/buildQuery.ts

@@ -0,0 +1,134 @@
+import type { SelectionMeta, SelectionFieldMeta } from './types.js'
+
+/**
+ * Query specification for a single field
+ */
+export interface QueryFieldSpec {
+	/** Name of the field as it appears in the output */
+	name: string
+	/** Path to the field in the source entity */
+	sourcePath: string[]
+	/** For nested objects/entities */
+	nested?: QuerySpec
+	/** Whether this is an array/collection */
+	isArray?: boolean
+	/** For has-many: filter parameters */
+	filter?: unknown
+	/** For has-many: ordering parameters */
+	orderBy?: unknown
+	/** For has-many: limit */
+	limit?: number
+	/** For has-many: offset */
+	offset?: number
+	/** For has-many: request totalCount via paginateRelation */
+	totalCount?: boolean
+}
+
+/**
+ * Query specification for fetching data.
+ * Backend adapters use this to construct their queries.
+ */
+export interface QuerySpec {
+	/** List of fields to fetch */
+	fields: QueryFieldSpec[]
+}
+
+/**
+ * Builds a QuerySpec from SelectionMeta.
+ * This is what gets passed to the backend adapter.
+ *
+ * @param meta - The selection metadata
+ */
+export function buildQueryFromSelection(meta: SelectionMeta): QuerySpec {
+	const fields: QueryFieldSpec[] = []
+
+	// Always include 'id' field if not already selected
+	// This is needed for entity identity and HasOneAccessor to detect if relation exists
+	if (!meta.fields.has('id')) {
+		fields.push({
+			name: 'id',
+			sourcePath: ['id'],
+		})
+	}
+
+	for (const [_alias, fieldMeta] of meta.fields) {
+		// Skip relation fields where no nested fields were selected.
+		// This occurs when a relation handle is passed as a prop (e.g., HasManyDataGrid's `field` prop)
+		// without any of its fields being read during JSX collection. The consuming component
+		// is expected to handle its own data fetching for that relation.
+		if (fieldMeta.isRelation && fieldMeta.nested && fieldMeta.nested.fields.size === 0) {
+			continue
+		}
+		fields.push(buildFieldSpecFromSelection(fieldMeta))
+	}
+
+	return { fields }
+}
+
+/**
+ * Builds a QueryFieldSpec from SelectionFieldMeta
+ */
+function buildFieldSpecFromSelection(meta: SelectionFieldMeta): QueryFieldSpec {
+	const spec: QueryFieldSpec = {
+		name: meta.alias,
+		sourcePath: [meta.fieldName],
+	}
+
+	if (meta.isArray) {
+		spec.isArray = true
+
+		// Add has-many parameters
+		if (meta.hasManyParams) {
+			if (meta.hasManyParams.filter !== undefined) {
+				spec.filter = meta.hasManyParams.filter
+			}
+			if (meta.hasManyParams.orderBy !== undefined) {
+				spec.orderBy = meta.hasManyParams.orderBy
+			}
+			if (meta.hasManyParams.limit !== undefined) {
+				spec.limit = meta.hasManyParams.limit
+			}
+			if (meta.hasManyParams.offset !== undefined) {
+				spec.offset = meta.hasManyParams.offset
+			}
+			if (meta.hasManyParams.totalCount) {
+				spec.totalCount = true
+			}
+		}
+
+		if (meta.nested) {
+			spec.nested = buildQueryFromSelection(meta.nested)
+		}
+	} else if (meta.nested) {
+		spec.nested = buildQueryFromSelection(meta.nested)
+	}
+
+	return spec
+}
+
+/**
+ * Collects all unique paths that need to be fetched.
+ * Useful for debugging and optimization.
+ */
+export function collectPaths(meta: SelectionMeta, basePath: string[] = []): string[][] {
+	const paths: string[][] = []
+
+	for (const [_alias, fieldMeta] of meta.fields) {
+		const fullPath = [...basePath, fieldMeta.fieldName]
+
+		if (fieldMeta.isArray && fieldMeta.nested) {
+			// For arrays, collect paths from nested metadata
+			const nestedPaths = collectPaths(fieldMeta.nested, fullPath)
+			paths.push(...nestedPaths)
+		} else if (fieldMeta.nested) {
+			// For nested objects, collect paths recursively
+			const nestedPaths = collectPaths(fieldMeta.nested, fullPath)
+			paths.push(...nestedPaths)
+		} else {
+			// Scalar field
+			paths.push(fullPath)
+		}
+	}
+
+	return paths
+}

package/src/selection/createFragment.ts

@@ -0,0 +1,50 @@
+import { createSelectionBuilder } from './createSelectionBuilder.js'
+import { SELECTION_META, type FluentFragment, type SelectionBuilder } from './types.js'
+
+/**
+ * Creates a reusable fragment using the fluent builder API.
+ *
+ * This is a curried function - first call provides the model type,
+ * second call provides the definer function.
+ *
+ * @example
+ * ```ts
+ * // Define a fragment
+ * const AuthorFragment = createFragment<Author>()(e =>
+ *   e.id().name().email()
+ * )
+ *
+ * // Use in useEntity
+ * const article = useEntity('Article', { id }, e =>
+ *   e.title().author(AuthorFragment)
+ * )
+ *
+ * // Or compose fragments
+ * const ArticleFragment = createFragment<Article>()(e =>
+ *   e.id().title()
+ *    .author(AuthorFragment)
+ *    .tags(TagFragment)
+ * )
+ * ```
+ */
+export function createFragment<TModel>() {
+	return function <TResult extends object>(
+		definer: (builder: SelectionBuilder<TModel>) => SelectionBuilder<TModel, TResult, object>,
+	): FluentFragment<TModel, TResult> {
+		// Create initial builder
+		const builder = createSelectionBuilder<TModel>()
+
+		// Execute definer to get final builder with accumulated selections
+		const resultBuilder = definer(builder)
+
+		// Extract metadata
+		const meta = resultBuilder[SELECTION_META]
+
+		return {
+			__meta: meta,
+			__resultType: undefined as unknown as TResult,
+			__modelType: undefined as unknown as TModel,
+			__isFragment: true,
+		}
+	}
+}