@contember/bindx 0.1.0

package/src/persistence/types.ts

@@ -0,0 +1,220 @@
+import type { ContemberMutationResult } from '../errors/pathMapper.js'
+import type { FieldError } from '../errors/types.js'
+
+// ==================== Mutation Data Collector ====================
+
+/**
+ * Interface for custom mutation data collectors.
+ * Used to build proper nested mutations for persistence operations.
+ */
+export interface MutationDataCollector {
+	/**
+	 * Collects mutation data for updating an existing entity.
+	 * Returns the mutation input or null if no changes.
+	 */
+	collectUpdateData(entityType: string, entityId: string): Record<string, unknown> | null
+
+	/**
+	 * Collects mutation data for creating a new entity.
+	 * Returns the mutation input or null if no data.
+	 */
+	collectCreateData?(entityType: string, entityId: string): Record<string, unknown> | null
+}
+
+// ==================== Persist Scope ====================
+
+/**
+ * Scope that encompasses all dirty entities
+ */
+export interface AllScope {
+	readonly type: 'all'
+}
+
+/**
+ * Scope for a single entity
+ */
+export interface EntityScope {
+	readonly type: 'entity'
+	readonly entityType: string
+	readonly entityId: string
+}
+
+/**
+ * Scope for specific fields of an entity
+ */
+export interface FieldsScope {
+	readonly type: 'fields'
+	readonly entityType: string
+	readonly entityId: string
+	readonly fields: readonly string[]
+}
+
+/**
+ * Scope for a specific relation of an entity
+ */
+export interface RelationScope {
+	readonly type: 'relation'
+	readonly entityType: string
+	readonly entityId: string
+	readonly relationName: string
+}
+
+/**
+ * Custom scope with explicit entity list
+ */
+export interface CustomScope {
+	readonly type: 'custom'
+	readonly entities: ReadonlyArray<{
+		readonly entityType: string
+		readonly entityId: string
+		readonly fields?: readonly string[]
+	}>
+}
+
+/**
+ * Union of all persist scope types
+ */
+export type PersistScope = AllScope | EntityScope | FieldsScope | RelationScope | CustomScope
+
+// ==================== Persistence Results ====================
+
+/**
+ * Result for a single field persist operation
+ */
+export interface FieldPersistResult {
+	readonly entityType: string
+	readonly entityId: string
+	readonly fieldName: string
+	readonly success: boolean
+	readonly error?: FieldError
+}
+
+/**
+ * Result for a single entity persist operation
+ */
+export interface EntityPersistResult {
+	readonly entityType: string
+	readonly entityId: string
+	readonly operation: 'create' | 'update' | 'delete'
+	readonly success: boolean
+	readonly error?: PersistError
+	readonly fieldResults?: readonly FieldPersistResult[]
+	/** Server-assigned ID for creates (when tempId was used) */
+	readonly persistedId?: string
+}
+
+/**
+ * Error information for failed persist operations
+ */
+export interface PersistError {
+	readonly message: string
+	readonly mutationResult?: ContemberMutationResult
+}
+
+/**
+ * Result of a batch/transaction persist operation
+ */
+export interface PersistenceResult {
+	/** Whether the entire operation succeeded */
+	readonly success: boolean
+	/** Results for each entity in the operation */
+	readonly results: readonly EntityPersistResult[]
+	/** Number of successfully persisted entities */
+	readonly successCount: number
+	/** Number of failed entities */
+	readonly failedCount: number
+	/** Number of entities skipped (e.g., already in-flight) */
+	readonly skippedCount: number
+}
+
+// ==================== Transaction Types ====================
+
+/**
+ * A single mutation in a transaction
+ */
+export interface TransactionMutation {
+	readonly entityType: string
+	readonly entityId: string
+	readonly operation: 'create' | 'update' | 'delete'
+	readonly data?: Record<string, unknown>
+}
+
+/**
+ * Result of a single mutation in a transaction
+ */
+export interface TransactionMutationResult {
+	readonly entityType: string
+	readonly entityId: string
+	readonly ok: boolean
+	/** Server-assigned ID for creates */
+	readonly persistedId?: string
+	readonly errorMessage?: string
+	readonly mutationResult?: ContemberMutationResult
+}
+
+/**
+ * Result of a transaction persist operation
+ */
+export interface TransactionResult {
+	/** Whether all mutations succeeded */
+	readonly ok: boolean
+	/** Results per mutation, in same order as input */
+	readonly results: readonly TransactionMutationResult[]
+}
+
+// ==================== Options ====================
+
+/**
+ * Update mode for persistence operations.
+ * - 'optimistic': Update UI immediately, revert on failure (default)
+ * - 'pessimistic': Wait for server confirmation before updating UI
+ */
+export type UpdateMode = 'optimistic' | 'pessimistic'
+
+/**
+ * Options for batch persist operations
+ */
+export interface BatchPersistOptions {
+	/**
+	 * Skip entities that are currently in-flight
+	 * @default true
+	 */
+	readonly skipInFlight?: boolean
+
+	/**
+	 * AbortSignal for cancellation
+	 */
+	readonly signal?: AbortSignal
+
+	/**
+	 * Automatically rollback optimistic changes when persistence fails.
+	 * When enabled, entity data, relations, and has-many lists are reverted
+	 * to their server state on failure.
+	 * @default false
+	 */
+	readonly rollbackOnError?: boolean
+
+	/**
+	 * Update mode for this operation.
+	 * - 'optimistic': Changes shown in UI immediately (default)
+	 * - 'pessimistic': Wait for server confirmation before showing in UI
+	 *
+	 * When using pessimistic mode:
+	 * - Changes are staged but not visible in UI until server confirms
+	 * - If server fails, staged changes are discarded (no UI change occurs)
+	 * - Loading state is properly tracked via isPersisting
+	 *
+	 * @default Uses provider-level default or 'optimistic'
+	 */
+	readonly updateMode?: UpdateMode
+
+	/**
+	 * Called for each entity before persistence
+	 */
+	readonly onEntityPersisting?: (entityType: string, entityId: string) => void | Promise<void>
+
+	/**
+	 * Called for each entity after persistence (success or failure)
+	 */
+	readonly onEntityPersisted?: (result: EntityPersistResult) => void
+}

package/src/schema/ContemberSchema.ts

@@ -0,0 +1,132 @@
+/**
+ * Types matching the Contember API schema introspection format.
+ * These types are compatible with binding-common's Schema.
+ */
+
+export type SchemaColumnType = 'Bool' | 'Date' | 'DateTime' | 'Double' | 'Enum' | 'Integer' | 'String' | 'Uuid' | 'Json' | string
+
+export interface SchemaColumn {
+	__typename: '_Column'
+	name: string
+	nullable: boolean
+	type: SchemaColumnType
+	enumName: string | null
+	defaultValue: string | number | boolean | null
+}
+
+export interface SchemaRelationOrderBy {
+	path: string[]
+	direction: 'asc' | 'desc'
+}
+
+interface BaseRelation {
+	__typename: '_Relation'
+	name: string
+	nullable: boolean | null
+	onDelete: 'restrict' | 'cascade' | 'setNull' | null
+	orderBy: SchemaRelationOrderBy[] | null
+	orphanRemoval: boolean | null
+	targetEntity: string
+	type: 'OneHasOne' | 'OneHasMany' | 'ManyHasOne' | 'ManyHasMany'
+}
+
+export interface OwningRelation extends BaseRelation {
+	side: 'owning'
+	inversedBy: string | null
+	ownedBy?: never
+}
+
+export interface InverseRelation extends BaseRelation {
+	side: 'inverse'
+	ownedBy: string
+	inversedBy?: never
+}
+
+export type SchemaRelation = OwningRelation | InverseRelation
+
+export type SchemaField = SchemaColumn | SchemaRelation
+
+export interface SchemaEntity {
+	name: string
+	customPrimaryAllowed: boolean
+	fields: Map<string, SchemaField>
+	unique: { fields: Set<string> }[]
+}
+
+export interface SchemaEnum {
+	name: string
+	values: string[]
+}
+
+/**
+ * Processed schema store with Maps for efficient lookup.
+ * This is the format used internally after loading from API.
+ */
+export interface ContemberSchemaStore {
+	entities: Map<string, SchemaEntity>
+	enums: Map<string, Set<string>>
+}
+
+/**
+ * Raw schema format as returned by the Contember API.
+ */
+export interface RawContemberSchema {
+	enums: { name: string; values: string[] }[]
+	entities: {
+		name: string
+		customPrimaryAllowed: boolean
+		fields: (SchemaColumn | (Omit<SchemaRelation, 'side'> & { side: 'owning' | 'inverse'; ownedBy?: string; inversedBy?: string | null }))[]
+		unique: { fields: string[] }[]
+	}[]
+}
+
+/**
+ * Schema class compatible with binding-common's Schema.
+ * Can be used directly or created from API response.
+ */
+export class ContemberSchema {
+	constructor(private readonly store: ContemberSchemaStore) {}
+
+	getEntity(entityName: string): SchemaEntity | undefined {
+		return this.store.entities.get(entityName)
+	}
+
+	getEntityNames(): string[] {
+		return Array.from(this.store.entities.keys())
+	}
+
+	getEntityField(entityName: string, fieldName: string): SchemaField | undefined {
+		return this.store.entities.get(entityName)?.fields.get(fieldName)
+	}
+
+	getEnumValues(enumName: string): string[] | undefined {
+		const values = this.store.enums.get(enumName)
+		return values ? Array.from(values) : undefined
+	}
+
+	/**
+	 * Creates a ContemberSchema from raw API response.
+	 */
+	static fromRaw(raw: RawContemberSchema): ContemberSchema {
+		const enums = new Map<string, Set<string>>()
+		for (const { name, values } of raw.enums) {
+			enums.set(name, new Set(values))
+		}
+
+		const entities = new Map<string, SchemaEntity>()
+		for (const entity of raw.entities) {
+			const fields = new Map<string, SchemaField>()
+			for (const field of entity.fields) {
+				fields.set(field.name, field as SchemaField)
+			}
+			entities.set(entity.name, {
+				name: entity.name,
+				customPrimaryAllowed: entity.customPrimaryAllowed,
+				fields,
+				unique: entity.unique.map(u => ({ fields: new Set(u.fields) })),
+			})
+		}
+
+		return new ContemberSchema({ entities, enums })
+	}
+}

package/src/schema/SchemaLoader.ts

@@ -0,0 +1,93 @@
+/**
+ * Loads schema from Contember Content API via GraphQL introspection.
+ */
+
+import { ContemberSchema, type RawContemberSchema } from './ContemberSchema.js'
+
+export interface SchemaLoaderClient {
+	execute<T>(query: string, options?: unknown): Promise<T>
+	apiUrl?: string
+}
+
+const SCHEMA_QUERY = `query {
+  schema {
+    enums {
+      name
+      values
+    }
+    entities {
+      name
+      customPrimaryAllowed
+      unique {
+        fields
+      }
+      fields {
+        __typename
+        name
+        type
+        nullable
+        ... on _Column {
+          enumName
+          defaultValue
+        }
+        ... on _Relation {
+          side
+          targetEntity
+          ownedBy
+          inversedBy
+          onDelete
+          orphanRemoval
+          orderBy {
+            path
+            direction
+          }
+        }
+      }
+    }
+  }
+}`
+
+/**
+ * Loads and caches schema from Contember Content API.
+ * Instance-level cache avoids cross-tenant collisions and test pollution.
+ */
+export class SchemaLoader {
+	private readonly cache = new Map<string, Promise<ContemberSchema>>()
+
+	/**
+	 * Loads schema from the API, with caching per API URL.
+	 */
+	async loadSchema(
+		client: SchemaLoaderClient,
+		options?: unknown,
+	): Promise<ContemberSchema> {
+		const cacheKey = client.apiUrl ?? 'default'
+
+		const existing = this.cache.get(cacheKey)
+		if (existing) {
+			return existing
+		}
+
+		const promise = (async () => {
+			const response = await client.execute<{ schema: RawContemberSchema }>(SCHEMA_QUERY, options)
+			return ContemberSchema.fromRaw(response.schema)
+		})()
+
+		this.cache.set(cacheKey, promise)
+		return promise
+	}
+
+	/**
+	 * Clears the schema cache.
+	 */
+	clearCache(): void {
+		this.cache.clear()
+	}
+
+	/**
+	 * Clears cache for a specific API URL.
+	 */
+	clearCacheFor(apiUrl: string): void {
+		this.cache.delete(apiUrl)
+	}
+}