@contember/bindx 0.1.0

package/src/selection/types.ts

@@ -0,0 +1,320 @@
+import type { ComponentBrand, AnyBrand } from '../brand/ComponentBrand.js'
+import type { EntityWhere, EntityOrderBy } from './queryTypes.js'
+
+/**
+ * Symbol used to store selection metadata on builder objects
+ */
+export const SELECTION_META = Symbol('SELECTION_META')
+
+/**
+ * Options for has-many relation selection with typed filter/orderBy
+ *
+ * @typeParam TItem - The related entity type (array item type)
+ * @typeParam TAlias - Optional alias for the field
+ */
+export interface HasManyOptions<
+	TItem = unknown,
+	TAlias extends string = string,
+> {
+	as?: TAlias
+	filter?: EntityWhere<TItem>
+	orderBy?: readonly EntityOrderBy<TItem>[]
+	limit?: number
+	offset?: number
+	totalCount?: boolean
+}
+
+/**
+ * Metadata for a selected field (runtime)
+ */
+export interface SelectionFieldMeta {
+	/** Original field name in the entity */
+	fieldName: string
+	/** Alias (output key) - defaults to fieldName */
+	alias: string
+	/** Full path to this field (for JSX components) */
+	path: string[]
+	/** Whether this is a relation (has nested fields) */
+	isRelation: boolean
+	/** Whether this is an array/has-many relation */
+	isArray: boolean
+	/** For relations: nested selection metadata */
+	nested?: SelectionMeta
+	/** For has-many: additional parameters */
+	hasManyParams?: {
+		filter?: unknown
+		orderBy?: unknown
+		limit?: number
+		offset?: number
+		totalCount?: boolean
+	}
+}
+
+/**
+ * Runtime metadata for a complete selection
+ */
+export interface SelectionMeta {
+	fields: Map<string, SelectionFieldMeta>
+}
+
+/**
+ * Extract item type from array
+ */
+type ArrayItemType<T> = T extends Array<infer U> ? U : never
+
+/**
+ * A fragment defined with the fluent builder
+ *
+ * @typeParam TModel - The entity model type
+ * @typeParam TResult - The selected fields result type
+ * @typeParam TBrand - Component brand type for validation (defaults to AnyBrand)
+ */
+export interface FluentFragment<
+	TModel,
+	TResult,
+	TBrand extends AnyBrand = AnyBrand,
+> {
+	/** Runtime metadata */
+	readonly __meta: SelectionMeta
+	/** Type brand for result type */
+	readonly __resultType: TResult
+	/** Type brand for model type */
+	readonly __modelType: TModel
+	/** Marker for type checking */
+	readonly __isFragment: true
+	/** Component brand for type-level tracking */
+	readonly __brand?: TBrand
+	/** Runtime brand symbols for validation */
+	readonly __brands?: Set<symbol>
+	/** Runtime roles for validation */
+	readonly __roles?: readonly string[]
+}
+
+/**
+ * Scalar method on selection builder - selects a scalar field
+ */
+export interface ScalarMethod<TEntity, K extends keyof TEntity, TSelected extends object, THasManyParams extends object> {
+	/** Select field with original name */
+	(): SelectionBuilder<TEntity, TSelected & Pick<TEntity, K>, THasManyParams>
+	/** Select field with alias */
+	<TAlias extends string>(options: { as: TAlias }): SelectionBuilder<
+		TEntity,
+		TSelected & { [P in TAlias]: TEntity[K] },
+		THasManyParams
+	>
+}
+
+/**
+ * Has-one method on selection builder - selects a relation to single entity
+ */
+export interface HasOneMethod<
+	TEntity,
+	K extends keyof TEntity,
+	TRelated,
+	TSelected extends object,
+	THasManyParams extends object,
+> {
+	/** Select with inline callback */
+	<TNestedSelected extends object>(
+		selector: (builder: SelectionBuilder<TRelated>) => SelectionBuilder<TRelated, TNestedSelected, object>,
+	): SelectionBuilder<TEntity, TSelected & { [P in K & string]: TNestedSelected }, THasManyParams>
+
+	/** Select with fragment */
+	<TFragmentResult extends object>(
+		fragment: FluentFragment<TRelated, TFragmentResult>,
+	): SelectionBuilder<TEntity, TSelected & { [P in K & string]: TFragmentResult }, THasManyParams>
+
+	/** Select with multiple fragments (merged) - result type is intersection of all fragment result types */
+	<T1 extends object, T2 extends object>(
+		fragment1: FluentFragment<TRelated, T1>,
+		fragment2: FluentFragment<TRelated, T2>,
+	): SelectionBuilder<TEntity, TSelected & { [P in K & string]: T1 & T2 }, THasManyParams>
+
+	/** Select with three fragments (merged) */
+	<T1 extends object, T2 extends object, T3 extends object>(
+		fragment1: FluentFragment<TRelated, T1>,
+		fragment2: FluentFragment<TRelated, T2>,
+		fragment3: FluentFragment<TRelated, T3>,
+	): SelectionBuilder<TEntity, TSelected & { [P in K & string]: T1 & T2 & T3 }, THasManyParams>
+
+	/** Select with alias and callback */
+	<TAlias extends string, TNestedSelected extends object>(
+		options: { as: TAlias },
+		selector: (builder: SelectionBuilder<TRelated>) => SelectionBuilder<TRelated, TNestedSelected, object>,
+	): SelectionBuilder<TEntity, TSelected & { [P in TAlias]: TNestedSelected }, THasManyParams>
+
+	/** Select with alias and fragment */
+	<TAlias extends string, TFragmentResult extends object>(
+		options: { as: TAlias },
+		fragment: FluentFragment<TRelated, TFragmentResult>,
+	): SelectionBuilder<TEntity, TSelected & { [P in TAlias]: TFragmentResult }, THasManyParams>
+
+	/** Select with alias and two fragments (merged) */
+	<TAlias extends string, T1 extends object, T2 extends object>(
+		options: { as: TAlias },
+		fragment1: FluentFragment<TRelated, T1>,
+		fragment2: FluentFragment<TRelated, T2>,
+	): SelectionBuilder<TEntity, TSelected & { [P in TAlias]: T1 & T2 }, THasManyParams>
+
+	/** Select with alias and three fragments (merged) */
+	<TAlias extends string, T1 extends object, T2 extends object, T3 extends object>(
+		options: { as: TAlias },
+		fragment1: FluentFragment<TRelated, T1>,
+		fragment2: FluentFragment<TRelated, T2>,
+		fragment3: FluentFragment<TRelated, T3>,
+	): SelectionBuilder<TEntity, TSelected & { [P in TAlias]: T1 & T2 & T3 }, THasManyParams>
+}
+
+/**
+ * Resolve alias from options or fall back to field name
+ */
+type ResolveAlias<K, TOptions> = TOptions extends { as: infer A extends string } ? A : K & string
+
+/**
+ * Has-many method on selection builder - selects a relation to multiple entities
+ */
+export interface HasManyMethod<
+	TEntity,
+	K extends keyof TEntity,
+	TItem,
+	TSelected extends object,
+	THasManyParams extends object,
+> {
+	/** Select with inline callback (no options) */
+	<TNestedSelected extends object>(
+		selector: (builder: SelectionBuilder<TItem>) => SelectionBuilder<TItem, TNestedSelected, object>,
+	): SelectionBuilder<
+		TEntity,
+		TSelected & { [P in K & string]: TNestedSelected[] },
+		THasManyParams & { [P in K & string]: object }
+	>
+
+	/** Select with fragment (no options) */
+	<TFragmentResult extends object>(
+		fragment: FluentFragment<TItem, TFragmentResult>,
+	): SelectionBuilder<
+		TEntity,
+		TSelected & { [P in K & string]: TFragmentResult[] },
+		THasManyParams & { [P in K & string]: object }
+	>
+
+	/** Select with two fragments (merged, no options) */
+	<T1 extends object, T2 extends object>(
+		fragment1: FluentFragment<TItem, T1>,
+		fragment2: FluentFragment<TItem, T2>,
+	): SelectionBuilder<
+		TEntity,
+		TSelected & { [P in K & string]: (T1 & T2)[] },
+		THasManyParams & { [P in K & string]: object }
+	>
+
+	/** Select with three fragments (merged, no options) */
+	<T1 extends object, T2 extends object, T3 extends object>(
+		fragment1: FluentFragment<TItem, T1>,
+		fragment2: FluentFragment<TItem, T2>,
+		fragment3: FluentFragment<TItem, T3>,
+	): SelectionBuilder<
+		TEntity,
+		TSelected & { [P in K & string]: (T1 & T2 & T3)[] },
+		THasManyParams & { [P in K & string]: object }
+	>
+
+	/** Select with options and callback */
+	<TOptions extends HasManyOptions<TItem>, TNestedSelected extends object>(
+		options: TOptions,
+		selector: (builder: SelectionBuilder<TItem>) => SelectionBuilder<TItem, TNestedSelected, object>,
+	): SelectionBuilder<
+		TEntity,
+		TSelected & { [P in ResolveAlias<K, TOptions>]: TNestedSelected[] },
+		THasManyParams & { [P in ResolveAlias<K, TOptions>]: TOptions }
+	>
+
+	/** Select with options and fragment */
+	<TOptions extends HasManyOptions<TItem>, TFragmentResult extends object>(
+		options: TOptions,
+		fragment: FluentFragment<TItem, TFragmentResult>,
+	): SelectionBuilder<
+		TEntity,
+		TSelected & { [P in ResolveAlias<K, TOptions>]: TFragmentResult[] },
+		THasManyParams & { [P in ResolveAlias<K, TOptions>]: TOptions }
+	>
+
+	/** Select with options and two fragments (merged) */
+	<TOptions extends HasManyOptions<TItem>, T1 extends object, T2 extends object>(
+		options: TOptions,
+		fragment1: FluentFragment<TItem, T1>,
+		fragment2: FluentFragment<TItem, T2>,
+	): SelectionBuilder<
+		TEntity,
+		TSelected & { [P in ResolveAlias<K, TOptions>]: (T1 & T2)[] },
+		THasManyParams & { [P in ResolveAlias<K, TOptions>]: TOptions }
+	>
+
+	/** Select with options and three fragments (merged) */
+	<TOptions extends HasManyOptions<TItem>, T1 extends object, T2 extends object, T3 extends object>(
+		options: TOptions,
+		fragment1: FluentFragment<TItem, T1>,
+		fragment2: FluentFragment<TItem, T2>,
+		fragment3: FluentFragment<TItem, T3>,
+	): SelectionBuilder<
+		TEntity,
+		TSelected & { [P in ResolveAlias<K, TOptions>]: (T1 & T2 & T3)[] },
+		THasManyParams & { [P in ResolveAlias<K, TOptions>]: TOptions }
+	>
+}
+
+/**
+ * Maps entity fields to their corresponding builder methods
+ */
+type SelectionBuilderMethods<TEntity, TSelected extends object, THasManyParams extends object> = {
+	[K in keyof TEntity]-?: TEntity[K] extends Array<infer U>
+		? HasManyMethod<TEntity, K, U, TSelected, THasManyParams>
+		: NonNullable<TEntity[K]> extends object
+			? HasOneMethod<TEntity, K, NonNullable<TEntity[K]>, TSelected, THasManyParams>
+			: ScalarMethod<TEntity, K, TSelected, THasManyParams>
+}
+
+/**
+ * The main fluent selection builder interface.
+ *
+ * @typeParam TEntity - The entity type being selected from
+ * @typeParam TSelected - Accumulated type of selected fields (grows with each selection)
+ * @typeParam THasManyParams - Record tracking has-many parameters for alias consistency
+ *
+ * @example
+ * ```ts
+ * // Select scalar fields
+ * e.id().title().content()
+ * // Type: { id: string, title: string, content: string }
+ *
+ * // Select with alias
+ * e.title({ as: 'headline' })
+ * // Type: { headline: string }
+ *
+ * // Select has-one relation
+ * e.author(a => a.name().email())
+ * // Type: { author: { name: string, email: string } }
+ *
+ * // Select has-many with options
+ * e.tags({ filter: { active: true } }, t => t.name())
+ * // Type: { tags: { name: string }[] }
+ * ```
+ */
+export type SelectionBuilder<TEntity, TSelected extends object = object, THasManyParams extends object = object> =
+	SelectionBuilderMethods<TEntity, TSelected, THasManyParams> & {
+		[SELECTION_META]: SelectionMeta
+		/** Type brand for the selected result */
+		readonly __selected: TSelected
+	}
+
+/**
+ * Extracts the selected type from a SelectionBuilder
+ */
+export type InferSelection<T> = T extends SelectionBuilder<infer _E, infer S, infer _P> ? S : never
+
+/**
+ * Type for the fluent definer function used in useEntity/useEntityList
+ */
+export type FluentDefiner<TModel, TResult extends object> = (
+	builder: SelectionBuilder<TModel>,
+) => SelectionBuilder<TModel, TResult, object>

package/src/store/DirtyTracker.ts

@@ -0,0 +1,117 @@
+import type { EntitySnapshotStore } from './EntitySnapshotStore.js'
+import type { EntityMetaStore } from './EntityMetaStore.js'
+import type { RelationStore } from './RelationStore.js'
+import { deepEqual } from '../utils/deepEqual.js'
+
+interface DirtyEntity {
+	entityType: string
+	entityId: string
+	changeType: 'create' | 'update' | 'delete'
+}
+
+/**
+ * Tracks dirty state across entities by comparing current data to server data.
+ *
+ * Receives shared references to SnapshotStore internals so it can read
+ * entity snapshots, metadata, and relation state without duplicating storage.
+ */
+export class DirtyTracker {
+	constructor(
+		private readonly entitySnapshots: EntitySnapshotStore,
+		private readonly meta: EntityMetaStore,
+		private readonly relations: RelationStore,
+	) {}
+
+	getAllDirtyEntities(): DirtyEntity[] {
+		const dirtyEntities: DirtyEntity[] = []
+
+		for (const key of this.entitySnapshots.keys()) {
+			const [entityType, ...idParts] = key.split(':')
+			const entityId = idParts.join(':')
+
+			if (!entityType || !entityId) continue
+
+			const entityKey = `${entityType}:${entityId}`
+
+			if (this.meta.isScheduledForDeletion(entityKey)) {
+				if (this.meta.existsOnServer(entityKey)) {
+					dirtyEntities.push({ entityType, entityId, changeType: 'delete' })
+				}
+				continue
+			}
+
+			if (!this.meta.existsOnServer(entityKey)) {
+				dirtyEntities.push({ entityType, entityId, changeType: 'create' })
+				continue
+			}
+
+			if (this.isEntityDirty(entityType, entityId)) {
+				dirtyEntities.push({ entityType, entityId, changeType: 'update' })
+			}
+		}
+
+		return dirtyEntities
+	}
+
+	getDirtyFields(entityType: string, entityId: string): string[] {
+		const key = `${entityType}:${entityId}`
+		const snapshot = this.entitySnapshots.get(key)
+
+		if (!snapshot) return []
+
+		const data = snapshot.data as Record<string, unknown>
+		const serverData = snapshot.serverData as Record<string, unknown>
+
+		const dirtyFields: string[] = []
+
+		for (const fieldName of Object.keys(data)) {
+			if (fieldName === 'id') continue
+
+			const currentValue = data[fieldName]
+			const serverValue = serverData[fieldName]
+
+			if (isRelationValue(currentValue) || isRelationValue(serverValue)) {
+				continue
+			}
+
+			if (!deepEqual(currentValue, serverValue)) {
+				dirtyFields.push(fieldName)
+			}
+		}
+
+		return dirtyFields
+	}
+
+	getDirtyRelations(entityType: string, entityId: string): string[] {
+		const keyPrefix = `${entityType}:${entityId}:`
+		return this.relations.getDirtyRelations(keyPrefix)
+	}
+
+	private isEntityDirty(entityType: string, entityId: string): boolean {
+		const dirtyFields = this.getDirtyFields(entityType, entityId)
+		if (dirtyFields.length > 0) return true
+
+		const keyPrefix = `${entityType}:${entityId}:`
+		const dirtyRelations = this.relations.getDirtyRelations(keyPrefix)
+		if (dirtyRelations.length > 0) return true
+
+		return false
+	}
+}
+
+/**
+ * Checks if a value represents a relation (object with id or array of objects).
+ */
+function isRelationValue(value: unknown): boolean {
+	if (value === null || value === undefined) return false
+
+	if (Array.isArray(value)) {
+		return value.length > 0 && typeof value[0] === 'object' && value[0] !== null
+	}
+
+	if (typeof value === 'object') {
+		return 'id' in (value as object)
+	}
+
+	return false
+}

package/src/store/EntityMetaStore.ts

@@ -0,0 +1,143 @@
+import type { LoadStatus } from './snapshots.js'
+import { isPersistedId, isPlaceholderId } from './entityId.js'
+import type { FieldError } from '../errors/types.js'
+
+/**
+ * Entity load state tracking.
+ */
+export interface EntityLoadState {
+	status: LoadStatus
+	error?: FieldError
+}
+
+/**
+ * Entity metadata for mutation generation.
+ */
+export interface EntityMeta {
+	/** Whether the entity exists on the server */
+	existsOnServer: boolean
+	/** Whether the entity is scheduled for deletion */
+	isScheduledForDeletion: boolean
+}
+
+/**
+ * Manages entity metadata, load states, persisting status, and temp ID mapping.
+ *
+ * Keys are pre-computed composite strings (e.g., "entityType:id").
+ * Follows the same pattern as ErrorStore and RelationStore.
+ */
+export class EntityMetaStore {
+	/** Load states keyed by "entityType:id" */
+	private readonly loadStates = new Map<string, EntityLoadState>()
+
+	/** Entity metadata keyed by "entityType:id" */
+	private readonly entityMetas = new Map<string, EntityMeta>()
+
+	/** Persisting status keyed by "entityType:id" */
+	private readonly persistingEntities = new Set<string>()
+
+	/** Mapping from temp ID to persisted ID (keyed by "entityType:tempId") */
+	private readonly tempToPersistedId = new Map<string, string>()
+
+	// ==================== Load State ====================
+
+	getLoadState(key: string): EntityLoadState | undefined {
+		return this.loadStates.get(key)
+	}
+
+	setLoadState(key: string, status: LoadStatus, error?: FieldError): void {
+		this.loadStates.set(key, { status, error })
+	}
+
+	clearLoadState(key: string): void {
+		this.loadStates.delete(key)
+	}
+
+	// ==================== Entity Meta ====================
+
+	getEntityMeta(key: string): EntityMeta | undefined {
+		return this.entityMetas.get(key)
+	}
+
+	setExistsOnServer(key: string, existsOnServer: boolean): void {
+		const existing = this.entityMetas.get(key) ?? { existsOnServer: false, isScheduledForDeletion: false }
+		this.entityMetas.set(key, { ...existing, existsOnServer })
+	}
+
+	existsOnServer(key: string): boolean {
+		return this.entityMetas.get(key)?.existsOnServer ?? false
+	}
+
+	scheduleForDeletion(key: string): void {
+		const existing = this.entityMetas.get(key) ?? { existsOnServer: false, isScheduledForDeletion: false }
+		this.entityMetas.set(key, { ...existing, isScheduledForDeletion: true })
+	}
+
+	unscheduleForDeletion(key: string): void {
+		const existing = this.entityMetas.get(key) ?? { existsOnServer: false, isScheduledForDeletion: false }
+		this.entityMetas.set(key, { ...existing, isScheduledForDeletion: false })
+	}
+
+	isScheduledForDeletion(key: string): boolean {
+		return this.entityMetas.get(key)?.isScheduledForDeletion ?? false
+	}
+
+	// ==================== Persisting State ====================
+
+	isPersisting(key: string): boolean {
+		return this.persistingEntities.has(key)
+	}
+
+	setPersisting(key: string, isPersisting: boolean): void {
+		if (isPersisting) {
+			this.persistingEntities.add(key)
+		} else {
+			this.persistingEntities.delete(key)
+		}
+	}
+
+	// ==================== Temp ID Mapping ====================
+
+	mapTempIdToPersistedId(key: string, persistedId: string): void {
+		this.tempToPersistedId.set(key, persistedId)
+		this.setExistsOnServer(key, true)
+	}
+
+	getPersistedId(key: string, id: string): string | null {
+		if (isPlaceholderId(id)) return null
+		if (isPersistedId(id)) return id
+		return this.tempToPersistedId.get(key) ?? null
+	}
+
+	isNewEntity(key: string, id: string): boolean {
+		if (isPlaceholderId(id)) return true
+		if (isPersistedId(id)) return false
+		return !this.tempToPersistedId.has(key)
+	}
+
+	// ==================== Bulk Operations ====================
+
+	exportMetas(keys: string[]): Map<string, EntityMeta> {
+		const result = new Map<string, EntityMeta>()
+		for (const key of keys) {
+			const meta = this.entityMetas.get(key)
+			if (meta) {
+				result.set(key, { ...meta })
+			}
+		}
+		return result
+	}
+
+	importMetas(metas: Map<string, EntityMeta>): void {
+		for (const [key, meta] of metas) {
+			this.entityMetas.set(key, { ...meta })
+		}
+	}
+
+	clear(): void {
+		this.loadStates.clear()
+		this.entityMetas.clear()
+		this.persistingEntities.clear()
+		this.tempToPersistedId.clear()
+	}
+}