@contember/bindx 0.1.51 → 0.1.53

package/src/store/RelationStore.ts

@@ -5,27 +5,33 @@ import {
 	type SentHasOneTransition,
 	type StoredRelationState,
 } from './HasOneStore.js'
+import { HasManyStore } from './HasManyStore.js'
 import {
-	HasManyStore,
-	computeDefaultOrderedIds,
 	type HasManyAdditionKind,
+	type HasManyRelationProjection,
 	type HasManyRemovalType,
+	type HasManyViewMembership,
+	type HasManyViewProjection,
 	type SentHasManyDelta,
 	type StoredHasManyState,
-} from './HasManyStore.js'
+} from './hasManyState.js'
 
 // Re-exported so existing imports from './RelationStore.js' keep resolving.
 export type { StoredRelationState } from './HasOneStore.js'
 export type { SentHasOneTransition } from './HasOneStore.js'
 export type {
 	HasManyAdditionKind,
+	HasManyRelationProjection,
 	HasManyRemovalType,
+	HasManyView,
+	HasManyViewMembership,
+	HasManyViewProjection,
+	PlannedHasManyAddition,
 	SentHasManyAddition,
 	SentHasManyDelta,
 	SentHasManyRemoval,
 	StoredHasManyState,
-} from './HasManyStore.js'
-export { computeDefaultOrderedIds } from './HasManyStore.js'
+} from './hasManyState.js'
 
 export type RelationReconciliationResult = 'applied' | 'conflict'
 
@@ -103,28 +109,58 @@ export class RelationStore implements Rekeyable {
 
 	// ==================== Has-Many Relations ====================
 
-	getOrCreateHasMany(key: string, serverIds?: string[]): StoredHasManyState {
-		return this.hasMany.getOrCreateHasMany(key, serverIds)
+	declareHasManyViewMembership(
+		entityType: string,
+		fieldName: string,
+		alias: string,
+		membership: HasManyViewMembership,
+	): void {
+		this.hasMany.declareViewMembership(entityType, fieldName, alias, membership)
 	}
 
-	getHasMany(key: string): StoredHasManyState | undefined {
+	getOrCreateHasMany(key: string, alias: string, serverIds?: string[]): void {
+		this.hasMany.getOrCreateHasMany(key, alias, serverIds)
+	}
+
+	/**
+	 * The raw stored state, views and all. Named apart from the projections above it:
+	 * {@link SnapshotStore.getHasMany} hands out a relation projection with no views,
+	 * and the undo / export paths that need the real thing must not get that by mistake.
+	 */
+	getHasManyState(key: string): StoredHasManyState | undefined {
 		return this.hasMany.getHasMany(key)
 	}
 
-	setHasManyServerIds(key: string, serverIds: string[]): void {
-		this.hasMany.setHasManyServerIds(key, serverIds)
+	getHasManyRelation(key: string): HasManyRelationProjection | undefined {
+		return this.hasMany.getRelationProjection(key)
 	}
 
-	planHasManyRemoval(key: string, itemId: string, type: HasManyRemovalType): void {
-		this.hasMany.planHasManyRemoval(key, itemId, type)
+	getHasManyView(key: string, alias: string): HasManyViewProjection {
+		return this.hasMany.getViewProjection(key, alias)
+	}
+
+	hasPendingHasManyWrites(key: string): boolean {
+		return this.hasMany.hasPendingWrites(key)
+	}
+
+	hasExplicitHasManyOrder(key: string, alias: string): boolean {
+		return this.hasMany.hasExplicitOrder(key, alias)
+	}
+
+	collectHasManyViewServerIds(key: string): ReadonlyMap<string, ReadonlySet<string>> {
+		return this.hasMany.collectViewServerIds(key)
 	}
 
-	planHasManyConnection(key: string, itemId: string): void {
-		this.hasMany.planHasManyConnection(key, itemId)
+	setHasManyServerIds(key: string, alias: string, serverIds: string[]): void {
+		this.hasMany.setHasManyServerIds(key, alias, serverIds)
+	}
+
+	planHasManyRemoval(key: string, itemId: string, type: HasManyRemovalType): void {
+		this.hasMany.planHasManyRemoval(key, itemId, type)
 	}
 
-	commitHasMany(key: string, newServerIds: string[]): void {
-		this.hasMany.commitHasMany(key, newServerIds)
+	planHasManyConnection(key: string, alias: string, itemId: string): void {
+		this.hasMany.planHasManyConnection(key, alias, itemId)
 	}
 
 	reconcileSentHasMany(
@@ -138,24 +174,24 @@ export class RelationStore implements Rekeyable {
 		this.hasMany.resetHasMany(key)
 	}
 
-	addToHasMany(key: string, itemId: string): void {
-		this.hasMany.addToHasMany(key, itemId)
+	addToHasMany(key: string, alias: string, itemId: string): void {
+		this.hasMany.addToHasMany(key, alias, itemId)
 	}
 
-	connectExistingToHasMany(key: string, itemId: string): void {
-		this.hasMany.connectExistingToHasMany(key, itemId)
+	connectExistingToHasMany(key: string, alias: string, itemId: string): void {
+		this.hasMany.connectExistingToHasMany(key, alias, itemId)
 	}
 
 	removeFromHasMany(key: string, itemId: string, removalType: HasManyRemovalType): boolean {
 		return this.hasMany.removeFromHasMany(key, itemId, removalType)
 	}
 
-	moveInHasMany(key: string, fromIndex: number, toIndex: number): void {
-		this.hasMany.moveInHasMany(key, fromIndex, toIndex)
+	moveInHasMany(key: string, alias: string, fromIndex: number, toIndex: number): void {
+		this.hasMany.moveInHasMany(key, alias, fromIndex, toIndex)
 	}
 
-	getHasManyOrderedIds(key: string): string[] {
-		return this.hasMany.getHasManyOrderedIds(key)
+	getHasManyOrderedIds(key: string, alias: string): string[] {
+		return this.hasMany.getHasManyOrderedIds(key, alias)
 	}
 
 	/**

package/src/store/ResponseOccurrenceIndex.ts

@@ -0,0 +1,224 @@
+import type { SelectionMeta } from '../selection/types.js'
+
+/** The schema knowledge the index needs: where a relation points and whether it is a list. */
+export interface RelationTargetResolver {
+	getRelationTarget(entityType: string, fieldName: string): string | undefined
+	isHasMany(entityType: string, fieldName: string): boolean
+}
+
+type EntityRecord = Record<string, unknown>
+
+interface PendingVisit {
+	readonly value: unknown
+	readonly entityType: string
+	readonly selection: SelectionMeta
+	readonly isList: boolean
+}
+
+/**
+ * Unites the occurrences of one entity within a single server response.
+ *
+ * One query can reach the same entity through several paths, each with its own
+ * sub-selection (`article.attachments` next to `article.sections.article.attachments`).
+ * Every occurrence is later written into the entity's snapshot, so without this
+ * the narrower one could replace fields the wider one carried. Occurrences of
+ * one response are equally fresh, so they are merged without any recency rule:
+ * each maps to the union of all of them, keyed by entity type and id. A scalar two
+ * occurrences disagree on (which one server read should not produce) takes the
+ * value of the occurrence visited last. The response is walked breadth first,
+ * relations in selection order and list items in list order, so the outcome
+ * follows from the response and the selection alone.
+ *
+ * The union is shallow. A relation value in it is one occurrence's raw value, and
+ * the related entities inside it resolve to their own unions when they are
+ * written, so relations inside relations unite level by level without rewriting
+ * the response.
+ *
+ * Reads never merge across responses: a later read replaces what an earlier one
+ * stored, as before.
+ */
+export class ResponseOccurrenceIndex {
+	private readonly unions = new WeakMap<object, Readonly<EntityRecord>>()
+
+	/**
+	 * Indexes a response read for `entityType` with `selection`. The type of every
+	 * nested occurrence comes from the schema through the selection's field names;
+	 * an occurrence whose type cannot be resolved is left out rather than matched
+	 * by id alone.
+	 *
+	 * Occurrences of one type at one selection node carry the same fields, so
+	 * their union changes nothing. Only types the selection reaches at two or more
+	 * nodes are collected, only the relations leading to them are walked, and a
+	 * selection with none skips the walk entirely (see {@link planOccurrenceWalk}).
+	 */
+	index(entityType: string, data: unknown, selection: SelectionMeta, schema: RelationTargetResolver): void {
+		const plan = planOccurrenceWalk(entityType, selection, schema)
+		if (plan.repeatedTypes.size === 0) {
+			return
+		}
+		const root: PendingVisit = { value: data, entityType, selection, isList: Array.isArray(data) }
+		const occurrencesByType = collectOccurrences(root, plan, schema)
+		for (const occurrencesById of occurrencesByType.values()) {
+			for (const occurrences of occurrencesById.values()) {
+				if (Array.isArray(occurrences)) {
+					this.unite(occurrences)
+				}
+			}
+		}
+	}
+
+	private unite(occurrences: readonly EntityRecord[]): void {
+		const union: EntityRecord = {}
+		for (const occurrence of occurrences) {
+			Object.assign(union, occurrence)
+		}
+		Object.freeze(union)
+		for (const occurrence of occurrences) {
+			this.unions.set(occurrence, union)
+		}
+	}
+
+	/** The union of every occurrence of this entity in its response, or the occurrence itself when it had no sibling. */
+	resolve(occurrence: EntityRecord): EntityRecord {
+		return this.unions.get(occurrence) ?? occurrence
+	}
+}
+
+/** Occurrences by entity type and id. A lone occurrence is kept as is; an array only appears once an id repeats. */
+type OccurrencesByType = Map<string, Map<unknown, EntityRecord | EntityRecord[]>>
+
+function collectOccurrences(root: PendingVisit, plan: OccurrenceWalkPlan, schema: RelationTargetResolver): OccurrencesByType {
+	const occurrencesByType: OccurrencesByType = new Map()
+	const pending: PendingVisit[] = [root]
+	for (let next = 0; next < pending.length; next++) {
+		const visit = pending[next]!
+		for (const entity of entitiesOf(visit.value, visit.isList)) {
+			if (plan.repeatedTypes.has(visit.entityType)) {
+				addOccurrence(occurrencesByType, visit.entityType, entity)
+			}
+			for (const fieldMeta of visit.selection.fields.values()) {
+				if (!fieldMeta.nested || !plan.nodesToWalk.has(fieldMeta.nested) || entity[fieldMeta.alias] == null) continue
+				const targetType = schema.getRelationTarget(visit.entityType, fieldMeta.fieldName)
+				if (targetType === undefined) continue
+				pending.push({
+					value: entity[fieldMeta.alias],
+					entityType: targetType,
+					selection: fieldMeta.nested,
+					isList: schema.isHasMany(visit.entityType, fieldMeta.fieldName),
+				})
+			}
+		}
+	}
+	return occurrencesByType
+}
+
+/** What walking a response needs from its selection. */
+export interface OccurrenceWalkPlan {
+	/** Entity types the selection reaches at two or more nodes, such as `article` and `article.sections.article`. Only these are united. */
+	readonly repeatedTypes: ReadonlySet<string>
+	/** Selection nodes on a path to a repeated type. The walk descends into no other. */
+	readonly nodesToWalk: ReadonlySet<SelectionMeta>
+}
+
+/**
+ * Plans the walk of one response. It depends only on the schema, the selection
+ * and its root type, and costs one pass over the selection tree, not over the
+ * response. It is computed per response rather than cached, because a selection
+ * can still grow after its first fetch (`mergeSelections` extends nested
+ * selections in place, and a fragment's selection is shared by every place
+ * that uses it).
+ */
+export function planOccurrenceWalk(entityType: string, selection: SelectionMeta, schema: RelationTargetResolver): OccurrenceWalkPlan {
+	const nodes = listSelectionNodes(entityType, selection, schema)
+	const repeatedTypes = findRepeatedTypes(nodes)
+	return { repeatedTypes, nodesToWalk: findNodesToWalk(nodes, repeatedTypes) }
+}
+
+interface SelectionNode {
+	readonly entityType: string
+	readonly selection: SelectionMeta
+	readonly parent: number | null
+}
+
+/** Every position in the selection tree, breadth first, each with the index of its parent. */
+function listSelectionNodes(entityType: string, selection: SelectionMeta, schema: RelationTargetResolver): readonly SelectionNode[] {
+	const nodes: SelectionNode[] = [{ entityType, selection, parent: null }]
+	for (let index = 0; index < nodes.length; index++) {
+		const node = nodes[index]!
+		for (const fieldMeta of node.selection.fields.values()) {
+			if (!fieldMeta.isRelation || !fieldMeta.nested) continue
+			const targetType = schema.getRelationTarget(node.entityType, fieldMeta.fieldName)
+			if (targetType !== undefined) {
+				nodes.push({ entityType: targetType, selection: fieldMeta.nested, parent: index })
+			}
+		}
+	}
+	return nodes
+}
+
+function findRepeatedTypes(nodes: readonly SelectionNode[]): ReadonlySet<string> {
+	const seenTypes = new Set<string>()
+	const repeatedTypes = new Set<string>()
+	for (const node of nodes) {
+		if (seenTypes.has(node.entityType)) {
+			repeatedTypes.add(node.entityType)
+		}
+		seenTypes.add(node.entityType)
+	}
+	return repeatedTypes
+}
+
+/**
+ * The selections on a path from the root to a repeated type. The climb tracks
+ * tree positions, not selection objects: a reused fragment is one selection
+ * object at several positions, and each position has ancestors of its own.
+ */
+function findNodesToWalk(nodes: readonly SelectionNode[], repeatedTypes: ReadonlySet<string>): ReadonlySet<SelectionMeta> {
+	const nodesToWalk = new Set<SelectionMeta>()
+	const climbed = new Set<number>()
+	nodes.forEach((node, index) => {
+		if (!repeatedTypes.has(node.entityType)) return
+		for (let position: number | null = index; position !== null && !climbed.has(position); position = nodes[position]!.parent) {
+			climbed.add(position)
+			nodesToWalk.add(nodes[position]!.selection)
+		}
+	})
+	return nodesToWalk
+}
+
+function addOccurrence(occurrencesByType: OccurrencesByType, entityType: string, entity: EntityRecord): void {
+	const id = entity['id']
+	if (typeof id !== 'string' && typeof id !== 'number') return
+	let occurrencesById = occurrencesByType.get(entityType)
+	if (!occurrencesById) {
+		occurrencesById = new Map()
+		occurrencesByType.set(entityType, occurrencesById)
+	}
+	const known = occurrencesById.get(id)
+	if (known === undefined) {
+		occurrencesById.set(id, entity)
+	} else if (Array.isArray(known)) {
+		known.push(entity)
+	} else if (known !== entity) {
+		occurrencesById.set(id, [known, entity])
+	}
+}
+
+/** The entity records a relation value holds: a has-one object, or a has-many array or connection (`{ edges: [{ node }] }`). */
+function entitiesOf(value: unknown, isList: boolean): readonly EntityRecord[] {
+	if (Array.isArray(value)) {
+		return value.filter(isRecord)
+	}
+	if (!isRecord(value)) {
+		return []
+	}
+	if (!isList) {
+		return [value]
+	}
+	const edges = value['edges']
+	return Array.isArray(edges) ? edges.map(edge => (isRecord(edge) ? edge['node'] : undefined)).filter(isRecord) : []
+}
+
+function isRecord(value: unknown): value is EntityRecord {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}