@contember/binding-common 2.0.0-alpha.17

package/src/treeParameters/TreeParameterMerger.ts

@@ -0,0 +1,352 @@
+import { GraphQlBuilder, Writable } from '@contember/client'
+import type {
+	Alias,
+	EntityEventListenerStore,
+	EventListenersStore,
+	ExpectedQualifiedEntityMutation,
+	ExpectedRelationMutation,
+	GenericEventsMap,
+	HasManyRelation,
+	HasOneRelation,
+	ParentEntityParameters,
+	QualifiedEntityList,
+	QualifiedSingleEntity,
+	RelativeSingleField,
+	SetOnCreate,
+	UnconstrainedQualifiedEntityList,
+	UnconstrainedQualifiedSingleEntity,
+	UniqueWhere,
+} from '../treeParameters'
+import { BindingError } from '../BindingError'
+
+export class TreeParameterMerger {
+	public static mergeHasOneRelationsWithSamePlaceholders(
+		original: HasOneRelation,
+		fresh: HasOneRelation,
+	): HasOneRelation {
+		return {
+			// Encoded within the placeholder
+			field: original.field,
+			filter: original.filter,
+			reducedBy: original.reducedBy,
+
+			// Not encoded within the placeholder
+			expectedMutation: this.mergeExpectedRelationMutation(original.expectedMutation, fresh.expectedMutation),
+			setOnCreate: this.mergeSetOnCreate(original.setOnCreate, fresh.setOnCreate),
+			isNonbearing: original.isNonbearing && fresh.isNonbearing,
+			// forceCreation: original.forceCreation || fresh.forceCreation,
+			eventListeners: this.mergeEventStore(original.eventListeners, fresh.eventListeners),
+		}
+	}
+
+	public static mergeHasManyRelationsWithSamePlaceholders(
+		original: HasManyRelation,
+		fresh: HasManyRelation,
+	): HasManyRelation {
+		if (original.initialEntityCount !== fresh.initialEntityCount) {
+			throw new BindingError(
+				`Detected hasMany relations on the same field '${original.field}' with different preferred initial ` +
+					`entity counts: '${original.initialEntityCount}' and '${fresh.initialEntityCount}' respectively.`,
+			)
+		}
+		return {
+			// Encoded within the placeholder
+			field: original.field,
+			filter: original.filter,
+			orderBy: original.orderBy,
+			offset: original.offset,
+			limit: original.limit,
+
+			// Not encoded within the placeholder
+			expectedMutation: this.mergeExpectedRelationMutation(original.expectedMutation, fresh.expectedMutation),
+			setOnCreate: this.mergeSetOnCreate(original.setOnCreate, fresh.setOnCreate),
+			// forceCreation: original.forceCreation || fresh.forceCreation,
+			isNonbearing: original.isNonbearing && fresh.isNonbearing,
+			initialEntityCount: original.initialEntityCount, // Handled above
+			childEventListeners: this.mergeEventStore(
+				original.childEventListeners,
+				fresh.childEventListeners,
+			),
+			eventListeners: this.mergeEventStore(original.eventListeners, fresh.eventListeners),
+		}
+	}
+
+	public static mergeEntitySubTreeParametersWithSamePlaceholders(
+		original: QualifiedSingleEntity | UnconstrainedQualifiedSingleEntity,
+		fresh: QualifiedSingleEntity | UnconstrainedQualifiedSingleEntity,
+	): QualifiedSingleEntity | UnconstrainedQualifiedSingleEntity {
+		if (original.isCreating) {
+			if (!fresh.isCreating) {
+				throw new BindingError()
+			}
+			return {
+				// Encoded within the placeholder
+				isCreating: original.isCreating,
+				isUnpersisted: original.isUnpersisted && fresh.isUnpersisted,
+				entityName: original.entityName,
+
+				// Not encoded within the placeholder
+				alias: this.mergeSubTreeAliases(original.alias, fresh.alias),
+				setOnCreate: this.mergeSetOnCreate(original.setOnCreate, fresh.setOnCreate),
+				// forceCreation: original.value.forceCreation || fresh.value.forceCreation,
+				expectedMutation: this.mergeExpectedQualifiedEntityMutation(original.expectedMutation, fresh.expectedMutation),
+				isNonbearing: original.isNonbearing && fresh.isNonbearing,
+				hasOneRelationPath: original.hasOneRelationPath, // TODO this is completely wrong.
+				eventListeners: this.mergeEventStore(original.eventListeners, fresh.eventListeners),
+			}
+		}
+		return {
+			// Encoded within the placeholder
+			isCreating: original.isCreating,
+			where: original.where,
+			entityName: original.entityName,
+			filter: original.filter,
+
+			// Not encoded within the placeholder
+			alias: this.mergeSubTreeAliases(original.alias, fresh.alias),
+			setOnCreate: this.mergeSetOnCreate(original.setOnCreate, fresh.setOnCreate),
+			// forceCreation: original.value.forceCreation || fresh.value.forceCreation,
+			expectedMutation: this.mergeExpectedQualifiedEntityMutation(original.expectedMutation, fresh.expectedMutation),
+			isNonbearing: original.isNonbearing && fresh.isNonbearing,
+			hasOneRelationPath: original.hasOneRelationPath, // TODO this is completely wrong.
+			eventListeners: this.mergeEventStore(original.eventListeners, fresh.eventListeners),
+		}
+	}
+
+	public static mergeEntityListSubTreeParametersWithSamePlaceholders(
+		original: QualifiedEntityList | UnconstrainedQualifiedEntityList,
+		fresh: QualifiedEntityList | UnconstrainedQualifiedEntityList,
+	): QualifiedEntityList | UnconstrainedQualifiedEntityList {
+		if (original.initialEntityCount !== fresh.initialEntityCount) {
+			throw new BindingError(
+				`Detected sub trees of the same entity '${original.entityName}' with different preferred initial ` +
+					`entity counts: '${original.initialEntityCount}' and '${fresh.initialEntityCount}' respectively.`,
+			)
+		}
+
+		if (original.isCreating) {
+			if (!fresh.isCreating) {
+				throw new BindingError()
+			}
+			return {
+				// Encoded within the placeholder
+				isCreating: original.isCreating,
+				isUnpersisted: original.isUnpersisted && fresh.isUnpersisted,
+				entityName: original.entityName,
+
+				// Not encoded within the placeholder
+				alias: this.mergeSubTreeAliases(original.alias, fresh.alias),
+				setOnCreate: this.mergeSetOnCreate(original.setOnCreate, fresh.setOnCreate),
+				// forceCreation: original.value.forceCreation || fresh.value.forceCreation,
+				expectedMutation: this.mergeExpectedQualifiedEntityMutation(original.expectedMutation, fresh.expectedMutation),
+				isNonbearing: original.isNonbearing && fresh.isNonbearing,
+				hasOneRelationPath: original.hasOneRelationPath, // TODO this is completely wrong.
+				childEventListeners: this.mergeEventStore(original.childEventListeners, fresh.childEventListeners),
+				eventListeners: this.mergeEventStore(original.eventListeners, fresh.eventListeners),
+				initialEntityCount: original.initialEntityCount, // Handled above
+			}
+		}
+		return {
+			// Encoded within the placeholder
+			isCreating: original.isCreating,
+			entityName: original.entityName,
+			filter: original.filter,
+			orderBy: original.orderBy,
+			offset: original.offset,
+			limit: original.limit,
+
+			// Not encoded within the placeholder
+			alias: this.mergeSubTreeAliases(original.alias, fresh.alias),
+			setOnCreate: this.mergeSetOnCreate(original.setOnCreate, fresh.setOnCreate),
+			// forceCreation: original.value.forceCreation || fresh.value.forceCreation,
+			expectedMutation: this.mergeExpectedQualifiedEntityMutation(original.expectedMutation, fresh.expectedMutation),
+			isNonbearing: original.isNonbearing && fresh.isNonbearing,
+			hasOneRelationPath: original.hasOneRelationPath, // TODO this is completely wrong.
+			childEventListeners: this.mergeEventStore(original.childEventListeners, fresh.childEventListeners),
+			eventListeners: this.mergeEventStore(original.eventListeners, fresh.eventListeners),
+			initialEntityCount: original.initialEntityCount, // Handled above
+		}
+	}
+
+	public static mergeSingleField(original: Omit<RelativeSingleField, 'hasOneRelationPath'>, fresh: Omit<RelativeSingleField, 'hasOneRelationPath'>): Omit<RelativeSingleField, 'hasOneRelationPath'> {
+		if (original.defaultValue !== undefined && fresh.defaultValue !== undefined && original.defaultValue !== fresh.defaultValue) {
+			throw new BindingError(`MarkerTreeGenerator merging: multiple fields "${original.field}" with different defaultValue found: ${JSON.stringify([original.defaultValue, fresh.defaultValue])}, `)
+		}
+		return {
+			field: original.field,
+			isNonbearing: original.isNonbearing && fresh.isNonbearing,
+			defaultValue: original.defaultValue ?? fresh.defaultValue,
+			eventListeners: this.mergeEventStore(original.eventListeners, fresh.eventListeners),
+		}
+	}
+
+
+	public static mergeSetOnCreate(original: SetOnCreate, fresh: SetOnCreate): SetOnCreate {
+		if (original === undefined && fresh === undefined) {
+			return undefined
+		}
+		if (original === undefined) {
+			return fresh
+		}
+		if (fresh === undefined) {
+			return original
+		}
+		const originalCopy: Writable<UniqueWhere> = { ...original }
+
+		for (const field in fresh) {
+			if (field in originalCopy) {
+				const fromOriginal = originalCopy[field]
+				const fromFresh = fresh[field]
+
+				if (fromOriginal instanceof GraphQlBuilder.GraphQlLiteral) {
+					if (fromFresh instanceof GraphQlBuilder.GraphQlLiteral) {
+						if (fromOriginal.value === fromFresh.value) {
+							// Good, do nothing.
+							continue
+						} else {
+							throw new BindingError() // TODO msg
+						}
+					} else {
+						throw new BindingError() // TODO msg
+					}
+				}
+				if (typeof fromOriginal === 'object') {
+					if (fromFresh instanceof GraphQlBuilder.GraphQlLiteral) {
+						throw new BindingError() // TODO msg
+					} else if (typeof fromFresh === 'object') {
+						const merged = this.mergeSetOnCreate(fromOriginal, fromFresh)
+						if (merged !== undefined) {
+							originalCopy[field] = merged
+						}
+						continue
+					} else {
+						throw new BindingError() // TODO msg
+					}
+				}
+				if (typeof fromFresh === 'string' || typeof fromFresh === 'number') {
+					if (fromOriginal === fromFresh) {
+						// Good, do nothing.
+						continue
+					} else {
+						throw new BindingError() // TODO msg
+					}
+				}
+				throw new BindingError() // TODO msg
+			} else {
+				originalCopy[field] = fresh[field]
+			}
+		}
+
+		return originalCopy
+	}
+
+	private static mergeSets<T>(original: Set<T>, fresh: Set<T>): Set<T> {
+		const combinedSet = new Set(original)
+		for (const item of fresh) {
+			combinedSet.add(item)
+		}
+		return combinedSet
+	}
+
+	public static mergeParentEntityParameters(
+		original: ParentEntityParameters | undefined,
+		fresh: ParentEntityParameters | undefined,
+	): ParentEntityParameters | undefined {
+		if (original === fresh) {
+			return original
+		}
+		if (original === undefined) {
+			return fresh
+		}
+		if (fresh === undefined) {
+			return original
+		}
+		return {
+			eventListeners: TreeParameterMerger.mergeEventStore(
+				original.eventListeners,
+				fresh.eventListeners,
+			),
+		}
+	}
+
+	public static mergeInParentEntity<
+		Original extends Record<Key, EntityEventListenerStore | undefined>,
+		Key extends keyof Original,
+	>(original: Original, key: Key, parentEntity: ParentEntityParameters | undefined): Original {
+		if (!parentEntity) {
+			return original
+		}
+
+		return {
+			...original,
+			[key]: TreeParameterMerger.mergeEventStore(original[key], parentEntity.eventListeners),
+		}
+	}
+
+
+	private static mergeEventStore<Events extends GenericEventsMap>(
+		original: EventListenersStore<Events> | undefined,
+		fresh: EventListenersStore<Events> | undefined,
+	): EventListenersStore<Events> | undefined {
+		if (original === undefined) {
+			if (fresh === undefined) {
+				return undefined
+			}
+			return fresh
+		}
+
+		if (fresh === undefined) {
+			return original
+		}
+
+		const store = original.clone()
+		store.append(fresh)
+
+		return store
+	}
+
+	private static mergeExpectedRelationMutation(
+		original: ExpectedRelationMutation,
+		fresh: ExpectedRelationMutation,
+	): ExpectedRelationMutation {
+		if (original === fresh) {
+			return original
+		}
+		if (original === 'none') {
+			return fresh
+		}
+		if (fresh === 'none') {
+			return original
+		}
+		return 'anyMutation'
+	}
+
+	private static mergeExpectedQualifiedEntityMutation(
+		original: ExpectedQualifiedEntityMutation,
+		fresh: ExpectedQualifiedEntityMutation,
+	): ExpectedQualifiedEntityMutation {
+		if (original === fresh) {
+			return original
+		}
+		if (original === 'none') {
+			return fresh
+		}
+		if (fresh === 'none') {
+			return original
+		}
+		return 'anyMutation'
+	}
+
+	private static mergeSubTreeAliases(
+		original: Set<Alias> | undefined,
+		fresh: Set<Alias> | undefined,
+	): Set<Alias> | undefined {
+		if (original === undefined) {
+			return fresh
+		}
+		if (fresh === undefined) {
+			return original
+		}
+		return this.mergeSets(original, fresh)
+	}
+}

package/src/treeParameters/defaults.ts

@@ -0,0 +1,33 @@
+export const LeafFieldDefaults = {
+	isNonbearing: false,
+} as const
+
+export const EntityCreationParametersDefaults = {
+	// forceCreation: false,
+	isNonbearing: false,
+} as const
+
+/*
+It can be somewhat tricky to understand how these parameters actually work. These are all only relevant when *creating
+a new entity*, NOT during updates.
+
+First, it is determined if any *bearing* field/relation has anything to be persisted. This occurs:
+- For fields if the resolved value (taking defaultValue into account) is not null
+- For relations if its children have anything to persist (TODO or if forceCreation is true.)
+
+If at least one of the bearing fields/relations have anything to persist or in the rare case when all fields/relations
+are nonbearing, the nonbearing fields/relations are also processed using the same method as described for bearing
+fields/relations.
+
+Lastly, setOnCreate comes to play. It doesn't influence whether the entity will be persisted or not but if after
+all of the above it is concluded that it will, the values from it are used.
+ */
+export const EntityListPreferencesDefaults = {
+	initialEntityCount: 0,
+}
+export const QualifiedEntityParametersDefaults = {
+	expectedMutation: 'anyMutation',
+} as const
+export const RelationDefaults = {
+	expectedMutation: 'anyMutation',
+} as const

package/src/treeParameters/helpers/index.ts

@@ -0,0 +1 @@
+export * from './wrapFilterInHasOnes'

package/src/treeParameters/helpers/wrapFilterInHasOnes.ts

@@ -0,0 +1,21 @@
+import { whereToFilter } from '@contember/client'
+import type { Filter, HasOneRelation } from '../../treeParameters'
+
+export const wrapFilterInHasOnes = (path: HasOneRelation[], filter: Filter): Filter => {
+	for (let i = path.length - 1; i >= 0; i--) {
+		const current = path[i]
+
+		if (current.reducedBy === undefined) {
+			filter = {
+				[current.field]: filter,
+			}
+		} else {
+			filter = {
+				[current.field]: {
+					and: [filter, whereToFilter(current.reducedBy)],
+				},
+			}
+		}
+	}
+	return filter
+}

package/src/treeParameters/index.ts

@@ -0,0 +1,14 @@
+export * from './primitives'
+export * from './helpers'
+
+
+export * from './EventListenersStore'
+export * from './Normalized'
+export * from './TreeParameterMerger'
+
+export * from './Sugared'
+export { LeafFieldDefaults } from './defaults'
+export { EntityCreationParametersDefaults } from './defaults'
+export { EntityListPreferencesDefaults } from './defaults'
+export { QualifiedEntityParametersDefaults } from './defaults'
+export { RelationDefaults } from './defaults'

package/src/treeParameters/primitives/Alias.ts

@@ -0,0 +1 @@
+export type Alias = string

package/src/treeParameters/primitives/EntityId.ts

@@ -0,0 +1,2 @@
+// This *CAN* include dummy values, not just uuids
+export type EntityId = string | number

package/src/treeParameters/primitives/EntityName.ts

@@ -0,0 +1,4 @@
+/*
+	Always starts with an uppercase letter.
+ */
+export type EntityName = string

package/src/treeParameters/primitives/EntityRealmKey.ts

@@ -0,0 +1,2 @@
+// An opaque value. It is *NOT* the same as EntityId.
+export type EntityRealmKey = string

package/src/treeParameters/primitives/ExpectedEntityCount.ts

@@ -0,0 +1 @@
+export type ExpectedEntityCount = 'upToOne' | 'possiblyMany'

package/src/treeParameters/primitives/ExpectedQualifiedEntityMutation.ts

@@ -0,0 +1 @@
+export type ExpectedQualifiedEntityMutation = 'none' | 'anyMutation'

package/src/treeParameters/primitives/ExpectedRelationMutation.ts

@@ -0,0 +1 @@
+export type ExpectedRelationMutation = 'none' | 'createOrDelete' | 'connectOrDisconnect' | 'anyMutation'

package/src/treeParameters/primitives/FieldName.ts

@@ -0,0 +1,7 @@
+/*
+	This type does not contain any query language. It is an atomic field (e.g. "surname" or "images")
+	that represents a single node within a tree. It can be a "leaf"-field or a relation.
+
+	Most usages of this should have been PlaceholderName. This needs fixed.
+ */
+export type FieldName = string

package/src/treeParameters/primitives/FieldValue.ts

@@ -0,0 +1,6 @@
+import type { VariableFieldValue } from '../../environment'
+import { JsonValue } from './Json'
+
+export type FieldValue = JsonValue
+
+export type OptionallyVariableFieldValue = FieldValue | VariableFieldValue

package/src/treeParameters/primitives/Filter.ts

@@ -0,0 +1,7 @@
+import type { GraphQlLiteral, Input } from '@contember/client'
+
+export type Filter<T = GraphQlLiteral> = Input.Where<Input.Condition<Input.ColumnValue<T>>>
+
+// E.g. [author.son.age < 123]
+// It is *always* enclosed within square brackets.
+export type SugaredFilter = Filter | string

package/src/treeParameters/primitives/Json.ts

@@ -0,0 +1,7 @@
+export interface JsonObject<Ext = never> {
+	[key: string]: JsonValue<Ext>
+}
+
+export interface JsonArray<Ext = never> extends Array<JsonValue<Ext>> {}
+
+export type JsonValue<Ext = never> = string | number | boolean | null | JsonObject<Ext> | JsonArray<Ext> | Ext

package/src/treeParameters/primitives/Limit.ts

@@ -0,0 +1 @@
+export type Limit = number

package/src/treeParameters/primitives/Offset.ts

@@ -0,0 +1 @@
+export type Offset = number

package/src/treeParameters/primitives/OrderBy.ts

@@ -0,0 +1,6 @@
+import type { CrudQueryBuilder, Input } from '@contember/client'
+
+export type OrderBy = Input.OrderBy<CrudQueryBuilder.OrderDirection>[]
+
+// E.g. items.order asc, items.content.name asc
+export type SugaredOrderBy = OrderBy | string

package/src/treeParameters/primitives/PlaceholderName.ts

@@ -0,0 +1,4 @@
+/*
+	This type should be used significantly more than it is. As of now, most usages of FieldName should really be this.
+ */
+export type PlaceholderName = string

package/src/treeParameters/primitives/RemovalType.ts

@@ -0,0 +1 @@
+export type RemovalType = 'disconnect' | 'delete'

package/src/treeParameters/primitives/Scalar.ts

@@ -0,0 +1 @@
+export type Scalar = string | number | boolean | null

package/src/treeParameters/primitives/SetOnCreate.ts

@@ -0,0 +1,8 @@
+import type { SugaredUniqueWhere, UniqueWhere } from './UniqueWhere'
+
+export type SetOnCreate = UniqueWhere | undefined
+
+
+// TODO maybe make an entirely new grammar that doesn't require parentheses.
+export type SugaredSetOnCreate = SugaredUniqueWhere | SugaredUniqueWhere[] | Exclude<SetOnCreate, undefined>
+

package/src/treeParameters/primitives/TreeRootId.ts

@@ -0,0 +1 @@
+export type TreeRootId = string

package/src/treeParameters/primitives/UniqueWhere.ts

@@ -0,0 +1,7 @@
+import type { GraphQlBuilder, Input } from '@contember/client'
+
+export type UniqueWhere<T = GraphQlBuilder.GraphQlLiteral> = Input.UniqueWhere<T>
+
+// E.g. (author.mother.id = 123)
+// It is *always* enclosed within parentheses
+export type SugaredUniqueWhere = UniqueWhere | string

package/src/treeParameters/primitives/index.ts

@@ -0,0 +1,20 @@
+export * from './Alias'
+export * from './EntityId'
+export * from './EntityName'
+export * from './EntityRealmKey'
+export * from './ExpectedEntityCount'
+export * from './ExpectedQualifiedEntityMutation'
+export * from './ExpectedRelationMutation'
+export * from './FieldName'
+export * from './FieldValue'
+export * from './Filter'
+export * from './Json'
+export * from './Limit'
+export * from './Offset'
+export * from './OrderBy'
+export * from './PlaceholderName'
+export * from './RemovalType'
+export * from './Scalar'
+export * from './SetOnCreate'
+export * from './TreeRootId'
+export * from './UniqueWhere'

package/src/tsconfig.json

@@ -0,0 +1,14 @@
+{
+	"extends": "../../../tsconfig.settings.json",
+	"compilerOptions": {
+		"outDir": "../dist/types",
+		"types": [
+			"vite/client"
+		]
+	},
+	"references": [
+		{ "path": "../../client/src" },
+		{ "path": "../../client-content/src" },
+		{ "path": "../../utilities/src" },
+	]
+}

package/src/types/AsyncBatchUpdatesOptions.ts

@@ -0,0 +1,8 @@
+import type { GraphQlClient } from '@contember/client'
+import type { BatchUpdatesOptions } from './BatchUpdatesOptions'
+
+export interface AsyncBatchUpdatesOptions extends BatchUpdatesOptions {
+	contentClient: GraphQlClient
+	systemClient: GraphQlClient
+	tenantClient: GraphQlClient
+}

package/src/types/BatchUpdatesOptions.ts

@@ -0,0 +1,9 @@
+import type { GetEntityByKey } from './GetEntityByKey'
+import type { GetEntityListSubTree } from './GetEntityListSubTree'
+import type { GetEntitySubTree } from './GetEntitySubTree'
+
+export interface BatchUpdatesOptions {
+	getEntityByKey: GetEntityByKey
+	getEntityListSubTree: GetEntityListSubTree
+	getEntitySubTree: GetEntitySubTree
+}

package/src/types/BindingOperations.ts

@@ -0,0 +1,26 @@
+import type { TreeFilter } from '@contember/client'
+import type { AsyncBatchUpdatesOptions } from './AsyncBatchUpdatesOptions'
+import type { BatchUpdatesOptions } from './BatchUpdatesOptions'
+import type { ExtendTree } from './ExtendTree'
+import type { Persist } from './Persist'
+import type { Environment } from '../environment'
+import { ReceivedDataTree } from './QueryRequestResponse'
+import { MarkerTreeRoot } from '../markers'
+
+export type FetchData<Node> = (fragment: Node, options?: { signal?: AbortSignal; environment?: Environment }) => Promise<{
+	data: ReceivedDataTree
+	markerTreeRoot: MarkerTreeRoot
+} | undefined>
+
+export type BatchDeferredUpdates = (performUpdates: (bindingOperations: BatchUpdatesOptions) => void) => void
+
+export interface BindingOperations<Node> extends AsyncBatchUpdatesOptions {
+	// addEventListener: ...
+	getTreeFilters: () => TreeFilter[]
+
+	extendTree: ExtendTree<Node>
+	fetchData: FetchData<Node>
+	batchDeferredUpdates: BatchDeferredUpdates
+	// discardSubTree: ...
+	persist: Persist
+}

package/src/types/DataBindingTransactionResult.ts

@@ -0,0 +1,4 @@
+import { MutationResult, TransactionResult } from '@contember/client'
+import { ReceivedEntityData } from './QueryRequestResponse'
+
+export type DataBindingTransactionResult = TransactionResult<Record<string, MutationResult<ReceivedEntityData>>>