@contember/bindx 0.1.0

package/dist/persistence/BatchPersister.d.ts

@@ -0,0 +1,142 @@
+import type { BackendAdapter } from '../adapter/types.js';
+import type { ActionDispatcher } from '../core/ActionDispatcher.js';
+import type { MutationDataCollector } from './types.js';
+import type { SchemaRegistry } from '../schema/SchemaRegistry.js';
+import type { SnapshotStore } from '../store/SnapshotStore.js';
+import type { UndoManager } from '../undo/UndoManager.js';
+import { ChangeRegistry } from './ChangeRegistry.js';
+import type { BatchPersistOptions, EntityPersistResult, PersistenceResult, PersistScope, UpdateMode } from './types.js';
+/**
+ * Options for BatchPersister
+ */
+export interface BatchPersisterOptions {
+    /**
+     * Custom mutation collector for building complex mutation inputs.
+     */
+    mutationCollector?: MutationDataCollector;
+    /**
+     * UndoManager instance to block during persist operations.
+     */
+    undoManager?: UndoManager;
+    /**
+     * Schema registry for mapping server errors to fields.
+     */
+    schema?: SchemaRegistry;
+    /**
+     * Default update mode for all persist operations.
+     * Can be overridden per-operation via BatchPersistOptions.
+     * @default 'optimistic'
+     */
+    defaultUpdateMode?: UpdateMode;
+}
+/**
+ * BatchPersister orchestrates multi-entity persistence with:
+ * - Deduplication (same entity referenced multiple times → single mutation)
+ * - Dependency ordering (new entities before entities referencing them)
+ * - Transactional execution (all-or-nothing via adapter.persistTransaction)
+ * - Field-level granularity (persist only specific fields)
+ */
+export declare class BatchPersister {
+    private readonly adapter;
+    private readonly store;
+    private readonly dispatcher;
+    private readonly changeRegistry;
+    private readonly mutationCollector?;
+    private readonly undoManager?;
+    private readonly schema?;
+    private readonly defaultUpdateMode;
+    constructor(adapter: BackendAdapter, store: SnapshotStore, dispatcher: ActionDispatcher, options?: BatchPersisterOptions);
+    /**
+     * Gets the default update mode for this persister.
+     */
+    getDefaultUpdateMode(): UpdateMode;
+    /**
+     * Gets the change registry for external access.
+     */
+    getChangeRegistry(): ChangeRegistry;
+    /**
+     * Persists all dirty entities in a single transaction.
+     */
+    persistAll(options?: BatchPersistOptions): Promise<PersistenceResult>;
+    /**
+     * Persists a single entity.
+     */
+    persist(entityType: string, entityId: string, options?: BatchPersistOptions): Promise<EntityPersistResult>;
+    /**
+     * Persists specific fields of an entity.
+     */
+    persistFields(entityType: string, entityId: string, fields: readonly string[], options?: BatchPersistOptions): Promise<EntityPersistResult>;
+    /**
+     * Persists entities matching the given scope.
+     */
+    persistScope(scope: PersistScope, options?: BatchPersistOptions): Promise<PersistenceResult>;
+    /**
+     * Collects entities to persist based on the scope.
+     */
+    private collectEntitiesForScope;
+    /**
+     * Sorts entities by dependencies (creates before updates that reference them).
+     */
+    private sortByDependencies;
+    /**
+     * Builds mutations for the given entities.
+     */
+    private buildMutations;
+    /**
+     * Collects create data, throwing if dirty relations exist without a MutationCollector.
+     */
+    private collectCreateDataWithRelationCheck;
+    /**
+     * Collects update data, throwing if dirty relations exist without a MutationCollector.
+     */
+    private collectUpdateDataWithRelationCheck;
+    /**
+     * Throws if the entity has dirty relations but no MutationCollector is configured.
+     */
+    private assertNoRelationChanges;
+    /**
+     * Collects data for specific fields only.
+     */
+    private collectFieldsData;
+    /**
+     * Simple update data collection (field diff).
+     */
+    private collectUpdateData;
+    /**
+     * Simple create data collection.
+     */
+    private collectCreateData;
+    /**
+     * Executes mutations as a transaction.
+     */
+    private executeTransaction;
+    /**
+     * Processes transaction result and commits/rolls back as needed.
+     * For pessimistic mode, restores captured state on success.
+     */
+    private processTransactionResult;
+    /**
+     * Captures the current state of entities for pessimistic mode.
+     * This allows us to restore the dirty state after a successful persist.
+     */
+    private captureEntityStates;
+    /**
+     * Restores a captured entity state and commits it.
+     * Used in pessimistic mode after successful server confirmation.
+     */
+    private restoreAndCommitEntityState;
+    /**
+     * Rolls back an entity's optimistic changes to server state.
+     * Handles all mutation types: create, update, and delete.
+     */
+    private rollbackEntity;
+    /**
+     * Maps server errors to entity fields/relations.
+     */
+    private mapServerErrors;
+    /**
+     * Cancels all in-flight operations.
+     */
+    cancelAll(): void;
+}
+//# sourceMappingURL=BatchPersister.d.ts.map

package/dist/persistence/BatchPersister.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BatchPersister.d.ts","sourceRoot":"","sources":["../../src/persistence/BatchPersister.ts"],"names":[],"mappings":"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"}

package/dist/persistence/ChangeRegistry.d.ts

@@ -0,0 +1,87 @@
+import type { SnapshotStore } from '../store/SnapshotStore.js';
+/**
+ * Information about a dirty entity
+ */
+export interface DirtyEntity {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly changeType: 'create' | 'update' | 'delete';
+    readonly dirtyFields: readonly string[];
+    readonly dirtyRelations: readonly string[];
+}
+/**
+ * ChangeRegistry tracks all dirty entities and in-flight persistence operations.
+ * It wraps SnapshotStore's dirty tracking methods and adds deduplication and
+ * in-flight tracking for batch persistence operations.
+ */
+export declare class ChangeRegistry {
+    private readonly store;
+    /** Set of entity keys currently being persisted (for batch operations) */
+    private readonly inFlight;
+    /** Subscribers to in-flight state changes */
+    private readonly subscribers;
+    constructor(store: SnapshotStore);
+    /**
+     * Gets the entity key for internal tracking.
+     */
+    private getKey;
+    /**
+     * Gets all dirty entities with their change types and dirty fields/relations.
+     */
+    getDirtyEntities(): readonly DirtyEntity[];
+    /**
+     * Gets dirty entities that are not currently in-flight.
+     */
+    getDirtyEntitiesNotInFlight(): readonly DirtyEntity[];
+    /**
+     * Gets dirty fields for a specific entity.
+     */
+    getDirtyFields(entityType: string, entityId: string): readonly string[];
+    /**
+     * Gets dirty relations for a specific entity.
+     */
+    getDirtyRelations(entityType: string, entityId: string): readonly string[];
+    /**
+     * Checks if an entity is currently being persisted (in a batch operation).
+     */
+    isInFlight(entityType: string, entityId: string): boolean;
+    /**
+     * Marks entities as in-flight (being persisted).
+     */
+    markInFlight(entities: ReadonlyArray<{
+        entityType: string;
+        entityId: string;
+    }>): void;
+    /**
+     * Clears in-flight status for entities.
+     */
+    clearInFlight(entities: ReadonlyArray<{
+        entityType: string;
+        entityId: string;
+    }>): void;
+    /**
+     * Clears all in-flight status.
+     */
+    clearAllInFlight(): void;
+    /**
+     * Gets the set of all in-flight entity keys.
+     */
+    getInFlightEntities(): ReadonlySet<string>;
+    /**
+     * Checks if any entity is currently in-flight.
+     */
+    hasInFlight(): boolean;
+    /**
+     * Checks if there are any dirty entities.
+     */
+    hasDirtyEntities(): boolean;
+    /**
+     * Subscribe to in-flight state changes.
+     */
+    subscribe(callback: () => void): () => void;
+    /**
+     * Notifies all subscribers of in-flight state changes.
+     */
+    private notifySubscribers;
+}
+//# sourceMappingURL=ChangeRegistry.d.ts.map

package/dist/persistence/ChangeRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChangeRegistry.d.ts","sourceRoot":"","sources":["../../src/persistence/ChangeRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAE9D;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACnD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1C;AAED;;;;GAIG;AACH,qBAAa,cAAc;IAOd,OAAO,CAAC,QAAQ,CAAC,KAAK;IANlC,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAE7C,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;gBAEvB,KAAK,EAAE,aAAa;IAEjD;;OAEG;IACH,OAAO,CAAC,MAAM;IAId;;OAEG;IACH,gBAAgB,IAAI,SAAS,WAAW,EAAE;IAY1C;;OAEG;IACH,2BAA2B,IAAI,SAAS,WAAW,EAAE;IAMrD;;OAEG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE;IAIvE;;OAEG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE;IAI1E;;OAEG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKzD;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,aAAa,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI;IAQrF;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,aAAa,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI;IAQtF;;OAEG;IACH,gBAAgB,IAAI,IAAI;IAKxB;;OAEG;IACH,mBAAmB,IAAI,WAAW,CAAC,MAAM,CAAC;IAI1C;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,gBAAgB,IAAI,OAAO;IAI3B;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAKzB"}

package/dist/persistence/ContemberSchemaMutationAdapter.d.ts

@@ -0,0 +1,16 @@
+import type { SchemaNames } from '@contember/client-content';
+import type { MutationSchemaProvider } from './MutationSchemaProvider.js';
+/**
+ * Adapter that wraps Contember SchemaNames to implement MutationSchemaProvider.
+ * Translates Contember's schema format (column/one/many) to the unified format (scalar/hasOne/hasMany).
+ */
+export declare class ContemberSchemaMutationAdapter implements MutationSchemaProvider {
+    private readonly schema;
+    constructor(schema: SchemaNames);
+    getScalarFields(entityType: string): readonly string[];
+    getRelationFields(entityType: string): readonly string[];
+    getRelationType(entityType: string, fieldName: string): 'hasOne' | 'hasMany' | undefined;
+    getRelationTarget(entityType: string, fieldName: string): string | undefined;
+    hasEntity(entityType: string): boolean;
+}
+//# sourceMappingURL=ContemberSchemaMutationAdapter.d.ts.map

package/dist/persistence/ContemberSchemaMutationAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContemberSchemaMutationAdapter.d.ts","sourceRoot":"","sources":["../../src/persistence/ContemberSchemaMutationAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAC5D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AAEzE;;;GAGG;AACH,qBAAa,8BAA+B,YAAW,sBAAsB;IAChE,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,WAAW;IAEhD,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE;IAStD,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE;IASxD,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS;IAYxF,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAa5E,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;CAGtC"}

package/dist/persistence/MutationCollector.d.ts

@@ -0,0 +1,96 @@
+import { type SnapshotStore } from '../store/SnapshotStore.js';
+import type { MutationSchemaProvider } from './MutationSchemaProvider.js';
+import type { MutationDataCollector } from './types.js';
+/**
+ * Result of collecting mutations for an entity
+ */
+export interface EntityMutationResult {
+    /** Type of mutation: create, update, or delete */
+    type: 'create' | 'update' | 'delete';
+    /** Entity type name */
+    entityType: string;
+    /** Entity ID (may be temp ID for creates) */
+    entityId: string;
+    /** The mutation data (for create/update) */
+    data?: Record<string, unknown>;
+}
+/**
+ * MutationCollector builds Contember-compatible mutation input
+ * by collecting changes from SnapshotStore including:
+ * - Scalar field changes
+ * - Has-one relation operations (connect, disconnect, delete, create, update)
+ * - Has-many relation operations (connect, disconnect, delete, create, update)
+ * - Entity creates and deletes
+ *
+ * This is a unified implementation that works with any schema provider
+ * implementing MutationSchemaProvider interface (SchemaRegistry, Contember SchemaNames via adapter).
+ */
+export declare class MutationCollector implements MutationDataCollector {
+    private readonly store;
+    private readonly schemaProvider;
+    private excludedEntityIds;
+    constructor(store: SnapshotStore, schemaProvider: MutationSchemaProvider);
+    /**
+     * Sets entity IDs that should be excluded from nested mutation generation.
+     * These entities get their own top-level mutations, so nested updates are skipped
+     * to avoid duplicate changes.
+     */
+    setExcludedEntities(ids: ReadonlySet<string>): void;
+    /**
+     * Collects all changes for an entity into appropriate mutation format.
+     * Returns the mutation result or null if no changes/entity doesn't exist.
+     */
+    collectMutation(entityType: string, entityId: string): EntityMutationResult | null;
+    /**
+     * Collects all changes for an entity into Contember UpdateDataInput format.
+     * Returns the mutation data or null if no changes.
+     */
+    collectUpdateData(entityType: string, entityId: string): Record<string, unknown> | null;
+    /**
+     * Collects data for creating a new entity.
+     * Returns the create data or null if empty.
+     */
+    collectCreateData(entityType: string, entityId: string): Record<string, unknown> | null;
+    /**
+     * Collects mutation data for specific fields only.
+     * Returns the mutation data containing only the specified fields.
+     */
+    collectFieldsData(entityType: string, entityId: string, fieldNames: readonly string[]): Record<string, unknown> | null;
+    /**
+     * Collects scalar field changes by comparing data to serverData.
+     */
+    private collectScalarChanges;
+    /**
+     * Collects has-one and has-many relation changes.
+     */
+    private collectRelationChanges;
+    /**
+     * Collects has-one relation operation.
+     * Returns the operation object or null if no change.
+     */
+    private collectHasOneOperation;
+    /**
+     * Collects has-one relation for create mutation.
+     */
+    private collectCreateOneRelation;
+    /**
+     * Collects has-many relation operations.
+     * Uses StoredHasManyState as the single source of truth for all operations.
+     * Returns array of operations or null if no changes.
+     */
+    private collectHasManyOperations;
+    /**
+     * Collects has-many relations for create mutation.
+     */
+    private collectCreateManyRelation;
+    /**
+     * Processes nested data to handle relation objects.
+     * Converts nested objects with 'id' to connect operations.
+     */
+    private processNestedData;
+    /**
+     * Checks if an entity ID represents an existing entity (persisted, not temp or placeholder).
+     */
+    private isExistingEntity;
+}
+//# sourceMappingURL=MutationCollector.d.ts.map

package/dist/persistence/MutationCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MutationCollector.d.ts","sourceRoot":"","sources":["../../src/persistence/MutationCollector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAA2B,MAAM,2BAA2B,CAAA;AAEvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAGvD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,kDAAkD;IAClD,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACpC,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC9B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,YAAW,qBAAqB;IAI7D,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAJhC,OAAO,CAAC,iBAAiB,CAAiC;gBAGxC,KAAK,EAAE,aAAa,EACpB,cAAc,EAAE,sBAAsB;IAGxD;;;;OAIG;IACH,mBAAmB,CAAC,GAAG,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI;IAMnD;;;OAGG;IACH,eAAe,CACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACd,oBAAoB,GAAG,IAAI;IAkD9B;;;OAGG;IACH,iBAAiB,CAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACd,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAqBjC;;;OAGG;IACH,iBAAiB,CAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACd,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IA8CjC;;;OAGG;IACH,iBAAiB,CAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IA6CjC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAqB5B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAwB9B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IA+D9B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA8BhC;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IA6EhC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IA+BjC;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAgDzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAGxB"}

package/dist/persistence/MutationSchemaProvider.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Interface for schema providers used by MutationCollector.
+ * Abstracts schema access to allow different schema implementations
+ * (SchemaRegistry, Contember SchemaNames) to be used interchangeably.
+ */
+export interface MutationSchemaProvider {
+    /**
+     * Gets all scalar (non-relation) field names for an entity.
+     */
+    getScalarFields(entityType: string): readonly string[];
+    /**
+     * Gets all relation field names for an entity.
+     */
+    getRelationFields(entityType: string): readonly string[];
+    /**
+     * Gets the relation type for a field.
+     * Returns undefined if the field is not a relation.
+     */
+    getRelationType(entityType: string, fieldName: string): 'hasOne' | 'hasMany' | undefined;
+    /**
+     * Gets the target entity type for a relation field.
+     * Returns undefined if the field is not a relation.
+     */
+    getRelationTarget(entityType: string, fieldName: string): string | undefined;
+    /**
+     * Checks if an entity type exists in the schema.
+     */
+    hasEntity(entityType: string): boolean;
+}
+//# sourceMappingURL=MutationSchemaProvider.d.ts.map

package/dist/persistence/MutationSchemaProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MutationSchemaProvider.d.ts","sourceRoot":"","sources":["../../src/persistence/MutationSchemaProvider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC;;OAEG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;IAEtD;;OAEG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;IAExD;;;OAGG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAA;IAExF;;;OAGG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IAE5E;;OAEG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAA;CACtC"}

package/dist/persistence/index.d.ts

@@ -0,0 +1,7 @@
+export { BatchPersister, type BatchPersisterOptions } from './BatchPersister.js';
+export { ChangeRegistry, type DirtyEntity } from './ChangeRegistry.js';
+export { MutationCollector, type EntityMutationResult } from './MutationCollector.js';
+export type { MutationSchemaProvider } from './MutationSchemaProvider.js';
+export { ContemberSchemaMutationAdapter } from './ContemberSchemaMutationAdapter.js';
+export type { MutationDataCollector, AllScope, EntityScope, FieldsScope, RelationScope, CustomScope, PersistScope, FieldPersistResult, EntityPersistResult, PersistError, PersistenceResult, TransactionMutation, TransactionMutationResult, TransactionResult, BatchPersistOptions, UpdateMode, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/persistence/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/persistence/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAChF,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtE,OAAO,EAAE,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AACrF,YAAY,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AACzE,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAA;AACpF,YAAY,EACX,qBAAqB,EACrB,QAAQ,EACR,WAAW,EACX,WAAW,EACX,aAAa,EACb,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,UAAU,GACV,MAAM,YAAY,CAAA"}

package/dist/persistence/types.d.ts

@@ -0,0 +1,189 @@
+import type { ContemberMutationResult } from '../errors/pathMapper.js';
+import type { FieldError } from '../errors/types.js';
+/**
+ * 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;
+}
+/**
+ * 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;
+/**
+ * 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;
+}
+/**
+ * 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[];
+}
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/persistence/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/persistence/types.ts"],"names":[],"mappings":"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"}