@stackbit/cms-core 0.2.1 → 0.3.0-develop.0

package/src/content-store.ts

@@ -18,7 +18,7 @@ import {
     Preset,
     PresetMap
 } from '@stackbit/sdk';
-import { append, deferWhileRunning, mapPromise, reducePromise } from '@stackbit/utils';
+import { append, DeferredPromise, deferredPromise, deferWhileRunning, mapPromise, reducePromise } from '@stackbit/utils';
 
 import * as ContentStoreTypes from './types';
 import { Timer } from './utils/timer';
@@ -33,7 +33,10 @@ import {
     getUserContextForSrcType,
     groupDocumentsByContentSource,
     groupModelsByContentSource,
-    updateOperationValueFieldWithCrossReference
+    isContentChangesEmpty,
+    isContentChangeResultEmpty,
+    updateOperationValueFieldWithCrossReference,
+    getErrorAtLine
 } from './content-store-utils';
 import {
     getSiteMapEntriesFromStackbitConfig,
@@ -48,6 +51,8 @@ import { mergeObjectWithDocument } from './utils/duplicate-document';
 import { normalizeModels, validateModels } from './utils/model-utils';
 import { IMAGE_MODEL } from './common/common-schema';
 import { getDocumentObjectFromPreset, getPresetFromDocument } from './utils/preset-utils';
+import { BackCompatContentSourceInterface, backwardCompatibleContentSource } from './utils/backward-compatibility';
+import { createConfigDelegate, getCreateConfigDelegateThunk } from './utils/config-delegate';
 import { GitService } from './services';
 import { CommandRunner } from '@stackbit/types';
 
@@ -70,6 +75,31 @@ export interface ContentSourceOptions {
 
 type ContentSourceData = ContentStoreTypes.ContentSourceData;
 type ContentSourceRawData = Omit<ContentSourceData, 'models' | 'modelMap' | 'documents' | 'documentMap'>;
+type ContentStoreEventQueue = ContentStoreEvent[];
+
+const ContentStoreEventType = {
+    YamlModelFilesChange: 'yamlModelFilesChange',
+    PresetFilesChange: 'presetFilesChange',
+    ContentSourceInvalidateSchema: 'contentSourceInvalidateSchema',
+    ContentSourceContentChange: 'contentSourceContentChange'
+} as const;
+
+type ContentStoreEvent =
+    | {
+          eventName: typeof ContentStoreEventType.YamlModelFilesChange;
+      }
+    | {
+          eventName: typeof ContentStoreEventType.PresetFilesChange;
+      }
+    | {
+          eventName: typeof ContentStoreEventType.ContentSourceInvalidateSchema;
+          contentSourceId: string;
+      }
+    | {
+          eventName: typeof ContentStoreEventType.ContentSourceContentChange;
+          contentSourceId: string;
+          contentChanges: CSITypes.ContentChanges;
+      };
 
 export const StackbitPresetModelName = 'stackbitPreset';
 
@@ -86,9 +116,9 @@ export class ContentStore {
     private readonly onContentChangeCallback: (contentChanges: ContentStoreTypes.ContentChangeResult) => void;
     private readonly handleConfigAssets: HandleConfigAssets;
     private readonly devAppRestartNeeded?: () => void;
-    private contentSources: CSITypes.ContentSourceInterface[] = [];
+    private contentSources: BackCompatContentSourceInterface[] = [];
     private contentSourceDataById: Record<string, ContentSourceData> = {};
-    private presetsContentSource?: CSITypes.ContentSourceInterface;
+    private presetsContentSource?: BackCompatContentSourceInterface;
     private contentUpdatesWatchTimer: Timer;
     private stackbitConfig: Config | null = null;
     private yamlModels: Model[] = [];
@@ -96,6 +126,8 @@ export class ContentStore {
     private modelExtensions: ModelExtension[] | null = null;
     private presets: PresetMap = {};
     private siteMapEntryGroups: SiteMapEntryGroups = {};
+    private processingContentSourcesPromise: DeferredPromise<void> | null = null;
+    private contentStoreEventQueue: ContentStoreEventQueue = [];
 
     constructor(options: ContentSourceOptions) {
         this.logger = options.logger.createLogger({ label: 'content-store' });
@@ -188,7 +220,7 @@ export class ContentStore {
      */
     private handleTimerTimeout() {
         for (const contentSourceInstance of this.contentSources) {
-            contentSourceInstance.stopWatchingContentUpdates();
+            contentSourceInstance.stopWatchingContentUpdates?.();
         }
     }
 
@@ -215,8 +247,6 @@ export class ContentStore {
     async onFilesChange(updatedFiles: string[]): Promise<void> {
         this.logger.debug('onFilesChange');
 
-        let schemaChanged = false;
-
         if (this.stackbitConfig && !this.stackbitConfig.modelExtensions) {
             // Check if any of the yaml models files were changed. If yaml model files were changed,
             // reload them and merge them with models defined in stackbit config.
@@ -224,9 +254,11 @@ export class ContentStore {
             const yamlModelsChanged = updatedFiles.find((updatedFile) => _.some(modelDirs, (modelDir) => updatedFile.startsWith(modelDir)));
             if (yamlModelsChanged) {
                 this.logger.debug('identified change in stackbit model files');
-                schemaChanged = true;
                 this.yamlModels = await this.loadYamlModels({ stackbitConfig: this.stackbitConfig });
                 this.configModels = this.mergeConfigModels(this.stackbitConfig.models ?? [], this.yamlModels);
+                this.pushContentSourceEvent({
+                    eventName: ContentStoreEventType.YamlModelFilesChange
+                });
             }
         }
 
@@ -236,62 +268,38 @@ export class ContentStore {
             const presetsChanged = updatedFiles.find((updatedFile) => _.some(presetDirs, (presetDir) => updatedFile.startsWith(presetDir)));
             if (presetsChanged && !this.usesContentSourcePresets()) {
                 this.logger.debug('identified change in stackbit preset files');
-                schemaChanged = true;
                 this.presets = await this.loadPresetsFromConfig({ stackbitConfig: this.stackbitConfig });
+                this.pushContentSourceEvent({
+                    eventName: ContentStoreEventType.PresetFilesChange
+                });
             }
         }
 
-        const contentSourceIdsWithChangedSchema: string[] = [];
-        const contentChangeEvents: { contentSourceId: string; contentChangeEvent: CSITypes.ContentChangeEvent }[] = [];
-
         for (const contentSourceInstance of this.contentSources) {
             const contentSourceId = getContentSourceIdForContentSource(contentSourceInstance);
             this.logger.debug(`call onFilesChange for contentSource: ${contentSourceId}`);
-            const onFilesChangeResult = (await contentSourceInstance.onFilesChange?.({ updatedFiles: updatedFiles })) ?? {};
-            this.logger.debug(`schemaChanged: ${onFilesChangeResult.schemaChanged}, has contentChangeEvent: ${!!onFilesChangeResult.contentChangeEvent}`);
-
-            // if schema is changed, there is no need to return contentChanges
-            // because schema changes reloads everything and implies content changes
-            if (onFilesChangeResult.schemaChanged) {
-                schemaChanged = true;
-                contentSourceIdsWithChangedSchema.push(contentSourceId);
-            } else if (onFilesChangeResult.contentChangeEvent) {
-                contentChangeEvents.push({ contentSourceId, contentChangeEvent: onFilesChangeResult.contentChangeEvent });
+            const onFilesChangeResult = await contentSourceInstance.onFilesChange({ updatedFiles: updatedFiles });
+
+            // If the schema was changed in a specific content source, there is no need to process and notify for content changes.
+            // Because the schema changes will trigger loadContentSourcesAndProcessData and reload all models and content of that
+            // content source and send the schemaChanged notification that will cause the Studio to reload the schema and documents.
+            if (onFilesChangeResult.invalidateSchema) {
+                this.logger.debug(`schema was invalidated for contentSource: ${contentSourceId}`);
+                this.pushContentSourceEvent({
+                    eventName: ContentStoreEventType.ContentSourceInvalidateSchema,
+                    contentSourceId: contentSourceId
+                });
+            } else if (!isContentChangesEmpty(onFilesChangeResult.contentChanges)) {
+                this.logger.debug(`content was changed for contentSource: ${contentSourceId}`);
+                this.pushContentSourceEvent({
+                    eventName: ContentStoreEventType.ContentSourceContentChange,
+                    contentSourceId: contentSourceId,
+                    contentChanges: onFilesChangeResult.contentChanges
+                });
             }
         }
 
-        // If the schema was changed, there is no need to accumulate or notify about content changes.
-        // The processData will update the store with the latest data. And once the Studio receives
-        // the schemaChanged notification it will reload all the models and the documents with their latest state.
-        if (schemaChanged) {
-            await this.loadContentSourcesAndProcessData({ init: false, contentSourceIds: contentSourceIdsWithChangedSchema });
-
-            this.onSchemaChangeCallback();
-        } else {
-            const contentChanges = contentChangeEvents.reduce((contentChanges: ContentStoreTypes.ContentChangeResult, { contentSourceId, contentChangeEvent }) => {
-                const contentChangeResult = this.onContentChange(contentSourceId, contentChangeEvent);
-                return {
-                    updatedDocuments: contentChanges.updatedDocuments.concat(contentChangeResult.updatedDocuments),
-                    updatedAssets: contentChanges.updatedAssets.concat(contentChangeResult.updatedAssets),
-                    deletedDocuments: contentChanges.deletedDocuments.concat(contentChangeResult.deletedDocuments),
-                    deletedAssets: contentChanges.deletedAssets.concat(contentChangeResult.deletedAssets)
-                };
-            }, {
-                updatedDocuments: [],
-                updatedAssets: [],
-                deletedDocuments: [],
-                deletedAssets: []
-            });
-
-            this.siteMapEntryGroups = await updateSiteMapEntriesWithContentChanges({
-                siteMapEntryGroups: this.siteMapEntryGroups,
-                contentChanges,
-                stackbitConfig: this.stackbitConfig,
-                contentSourceDataById: this.contentSourceDataById
-            });
-
-            this.onContentChangeCallback(contentChanges);
-        }
+        await this.processContentStoreEvents();
     }
 
     private async loadYamlModels({ stackbitConfig }: { stackbitConfig: Config }): Promise<Model[]> {
@@ -371,19 +379,20 @@ export class ContentStore {
      */
     private async loadContentSourcesAndProcessData({ init, contentSourceIds }: { init: boolean; contentSourceIds?: string[] }) {
         this.logger.debug('loadContentSourcesAndProcessData', { init, contentSourceIds });
+        this.processingContentSourcesPromise = deferredPromise();
 
-        const contentSources = this.stackbitConfig?.contentSources ?? [];
+        const contentSources = (this.stackbitConfig?.contentSources ?? []).map((contentSource) => {
+            return backwardCompatibleContentSource(contentSource);
+        });
 
-        const promises = contentSources.map(
-            (contentSourceInstance): Promise<ContentSourceRawData> => {
-                const contentSourceId = getContentSourceIdForContentSource(contentSourceInstance);
-                if (init || !contentSourceIds || contentSourceIds.includes(contentSourceId)) {
-                    return this.loadContentSourceData({ contentSourceInstance, init });
-                } else {
-                    return Promise.resolve(_.omit(this.contentSourceDataById[contentSourceId], ['models', 'modelMap', 'documents', 'documentMap']));
-                }
+        const promises = contentSources.map((contentSourceInstance): Promise<ContentSourceRawData> => {
+            const contentSourceId = getContentSourceIdForContentSource(contentSourceInstance);
+            if (init || !contentSourceIds || contentSourceIds.includes(contentSourceId)) {
+                return this.loadContentSourceData({ contentSourceInstance, init });
+            } else {
+                return Promise.resolve(_.omit(this.contentSourceDataById[contentSourceId], ['models', 'modelMap', 'documents', 'documentMap']));
             }
-        );
+        });
 
         const contentSourceRawDataArr = await Promise.all(promises);
 
@@ -391,13 +400,10 @@ export class ContentStore {
         for (let i = 0; i < contentSources.length; i++) {
             const contentSourceDataRaw = contentSourceRawDataArr[i];
             if (contentSourceDataRaw?.csiModelMap?.[StackbitPresetModelName]) {
-                this.presetsContentSource = contentSources[i];
-                if (this.presetsContentSource) {
-                    const contentSourceId = getContentSourceIdForContentSource(this.presetsContentSource);
-                    // reload presets from content source only if needed
-                    if (init || !contentSourceIds || contentSourceIds.includes(contentSourceId)) {
-                        this.presets = await this.loadPresetsFromContentSource(contentSourceDataRaw);
-                    }
+                this.presetsContentSource = contentSourceDataRaw.instance;
+                // reload presets from content source only if needed
+                if (init || !contentSourceIds || contentSourceIds.includes(contentSourceDataRaw.id)) {
+                    this.presets = await this.loadPresetsFromContentSource(contentSourceDataRaw);
                 }
                 break;
             }
@@ -422,47 +428,302 @@ export class ContentStore {
             stackbitConfig: this.stackbitConfig,
             contentSourceDataById: this.contentSourceDataById
         });
+
+        if (!init) {
+            this.onSchemaChangeCallback();
+        }
+
+        const processingPromise = this.processingContentSourcesPromise;
+        this.processingContentSourcesPromise = null;
+
+        // Do not "await" on processContentStoreEvents as it may introduce a deadlock with
+        // the nested loadContentSourcesAndProcessData call which is wrapped by deferWhileRunning.
+        this.processContentStoreEvents()
+            .catch((error) => {
+                this.logger.error('error processing content source events', { error });
+            })
+            .finally(() => {
+                processingPromise.resolve();
+            });
+    }
+
+    private async processContentStoreEvents() {
+        // If the ContentStore is currently loading content sources, return to prevent parallel data updates.
+        // This method will be called once current loading cycle ends.
+        if (this.processingContentSourcesPromise) {
+            return this.processingContentSourcesPromise.promise;
+        }
+
+        const contentSourceIdsWithInvalidatedSchema: string[] = [];
+        const contentChanges: ContentStoreTypes.ContentChangeResult = {
+            updatedDocuments: [],
+            updatedAssets: [],
+            deletedDocuments: [],
+            deletedAssets: []
+        };
+        let invalidateSchema = false;
+        let presetsUpdated = false;
+
+        const contentSourceEvents = this.contentStoreEventQueue;
+        this.contentStoreEventQueue = [];
+        for (const contentSourceEvent of contentSourceEvents) {
+            if (
+                contentSourceEvent.eventName === ContentStoreEventType.YamlModelFilesChange ||
+                contentSourceEvent.eventName === ContentStoreEventType.PresetFilesChange
+            ) {
+                invalidateSchema = true;
+            } else if (contentSourceEvent.eventName === ContentStoreEventType.ContentSourceInvalidateSchema) {
+                invalidateSchema = true;
+                contentSourceIdsWithInvalidatedSchema.push(contentSourceEvent.contentSourceId);
+            } else if (contentSourceEvent.eventName === ContentStoreEventType.ContentSourceContentChange) {
+                const result = this.onContentChange(contentSourceEvent.contentSourceId, contentSourceEvent.contentChanges);
+                contentChanges.updatedDocuments = contentChanges.updatedDocuments.concat(result.contentChangeResult.updatedDocuments);
+                contentChanges.updatedAssets = contentChanges.updatedAssets.concat(result.contentChangeResult.updatedAssets);
+                contentChanges.deletedDocuments = contentChanges.deletedDocuments.concat(result.contentChangeResult.deletedDocuments);
+                contentChanges.deletedAssets = contentChanges.deletedAssets.concat(result.contentChangeResult.deletedAssets);
+                if (result.presetsUpdated) {
+                    presetsUpdated = true;
+                }
+            }
+        }
+
+        // If the schema was changed, call loadContentSourcesAndProcessData method, this will reload all the SiteMapEntries and call the onSchemaChangeCallback.
+        // As soon as the Studio receives the schemaChanged notification it will reload all the models and the documents.
+        if (invalidateSchema) {
+            await this.loadContentSourcesAndProcessData({
+                init: false,
+                contentSourceIds: contentSourceIdsWithInvalidatedSchema
+            });
+        } else {
+            // If the schema wasn't changed, update SiteMapEntries with the changed content.
+            this.siteMapEntryGroups = await updateSiteMapEntriesWithContentChanges({
+                siteMapEntryGroups: this.siteMapEntryGroups,
+                contentChanges: contentChanges,
+                stackbitConfig: this.stackbitConfig,
+                contentSourceDataById: this.contentSourceDataById
+            });
+            // If presets were updated, call onSchemaChangeCallback to notify the Studio.
+            // The Studio will refresh the models and the documents, so no need to notify
+            // content changes in this case.
+            if (presetsUpdated) {
+                this.onSchemaChangeCallback();
+            } else if (!isContentChangeResultEmpty(contentChanges)) {
+                this.onContentChangeCallback(contentChanges);
+            }
+        }
+    }
+
+    private pushContentSourceEvent(contentStoreEvent: ContentStoreEvent) {
+        if (contentStoreEvent.eventName === ContentStoreEventType.ContentSourceContentChange) {
+            // If a content source enqueued the 'contentSourceInvalidateSchema' event,
+            // don't push the 'contentSourceContentChange' event, because 'contentSourceInvalidateSchema'
+            // will reload all the content source data.
+            const hasContentSourceSchemaChangeEvent = this.contentStoreEventQueue.find(
+                (event) =>
+                    event.eventName === ContentStoreEventType.ContentSourceInvalidateSchema && event.contentSourceId === contentStoreEvent.contentSourceId
+            );
+            if (!hasContentSourceSchemaChangeEvent) {
+                this.contentStoreEventQueue.push(contentStoreEvent);
+            }
+        } else if (contentStoreEvent.eventName === ContentStoreEventType.ContentSourceInvalidateSchema) {
+            // Clear any 'contentSourceContentChange' events for a content source,
+            // the 'contentSourceInvalidateSchema' will reload all the content source data.
+            this.clearEventsForContentSourceId(contentStoreEvent.contentSourceId);
+            this.contentStoreEventQueue.push(contentStoreEvent);
+        } else if (contentStoreEvent.eventName === ContentStoreEventType.YamlModelFilesChange) {
+            this.contentStoreEventQueue = this.contentStoreEventQueue.filter((event) => event.eventName !== ContentStoreEventType.YamlModelFilesChange);
+            this.contentStoreEventQueue.push(contentStoreEvent);
+        } else if (contentStoreEvent.eventName === ContentStoreEventType.PresetFilesChange) {
+            this.contentStoreEventQueue = this.contentStoreEventQueue.filter((event) => event.eventName !== ContentStoreEventType.PresetFilesChange);
+            this.contentStoreEventQueue.push(contentStoreEvent);
+        }
+    }
+
+    private clearEventsForContentSourceId(contentSourceId: string) {
+        this.contentStoreEventQueue = this.contentStoreEventQueue.filter((contentSourceEvent) => {
+            if (
+                contentSourceEvent.eventName === ContentStoreEventType.ContentSourceContentChange ||
+                contentSourceEvent.eventName === ContentStoreEventType.ContentSourceInvalidateSchema
+            ) {
+                return contentSourceEvent.contentSourceId !== contentSourceId;
+            }
+            return true;
+        });
     }
 
     private async loadContentSourceData({
         contentSourceInstance,
         init
     }: {
-        contentSourceInstance: CSITypes.ContentSourceInterface;
+        contentSourceInstance: BackCompatContentSourceInterface;
         init: boolean;
     }): Promise<ContentSourceRawData> {
         const contentSourceId = getContentSourceIdForContentSource(contentSourceInstance);
         this.logger.debug('loadContentSourceData', { contentSourceId, init });
 
+        // clear content source events emitted by this content source because all the content source data is reloaded
+        this.clearEventsForContentSourceId(contentSourceId);
+
+        const localCache: Partial<
+            Pick<ContentSourceRawData, 'csiSchema' | 'csiModels' | 'csiModelMap' | 'locales' | 'csiDocuments' | 'csiDocumentMap' | 'csiAssets' | 'csiAssetMap'>
+        > = {};
+
+        const getContentSourceDataForCurrentInstance = (methodName: keyof CSITypes.Cache | 'getModelMap' | 'getDocument' | 'getAsset') => {
+            const contentSourceData = this.contentSourceDataById[contentSourceId];
+            if (!contentSourceData) {
+                // When loading the content sources for the first time, this.contentSourceDataById will be empty.
+                // However, while being loaded, content sources may call cache methods, for example a content
+                // source may call getModelByName from within getDocuments. In this case, return locally cached data.
+                if (this.processingContentSourcesPromise) {
+                    return localCache;
+                }
+                const atLine = getErrorAtLine(2, getContentSourceDataForCurrentInstance);
+                const errorMessage = `Error executing 'cache.${methodName}' method${atLine}. The content source with id '${contentSourceId}' was not found.`;
+                this.logger.error(errorMessage);
+                return;
+            }
+            if (contentSourceData.instance !== contentSourceInstance) {
+                const atLine = getErrorAtLine(2, getContentSourceDataForCurrentInstance);
+                const errorMessage =
+                    `Content source life cycle error! The content source with id '${contentSourceId}' called the 'cache.${methodName}' ` +
+                    `method${atLine} after the destroy() method was called.`;
+                this.logger.error(errorMessage);
+                return;
+            }
+            // While loading the content source, it may call cache methods, when this happens, return the
+            // stale data overridden with the most frequent loaded data
+            if (this.processingContentSourcesPromise) {
+                return Object.assign(contentSourceData, localCache);
+            }
+            return contentSourceData;
+        };
+
+        const cache: CSITypes.Cache = {
+            getSchema: () => {
+                const contentSourceData = getContentSourceDataForCurrentInstance('getSchema');
+                if (!contentSourceData?.csiSchema) {
+                    const atLine = getErrorAtLine(1);
+                    const errorMessage =
+                        `Content source life cycle error! The content source with id '${contentSourceId}' called the 'cache.getSchema' ` +
+                        `method${atLine} before the content source's getSchema() method was called.`;
+                    this.logger.error(errorMessage);
+                    return { models: [], locales: [], context: null };
+                }
+                return contentSourceData.csiSchema;
+            },
+            getModelByName: (modelName) => {
+                const contentSourceData = getContentSourceDataForCurrentInstance('getModelByName');
+                if (!contentSourceData?.csiModelMap) {
+                    const atLine = getErrorAtLine(1);
+                    const errorMessage =
+                        `Content source life cycle error! The content source with id '${contentSourceId}' called the 'cache.getModelByName' ` +
+                        `method${atLine} before the content source's getSchema() method was called.`;
+                    this.logger.error(errorMessage);
+                    return;
+                }
+                return contentSourceData.csiModelMap[modelName];
+            },
+            getDocuments: () => {
+                const contentSourceData = getContentSourceDataForCurrentInstance('getDocuments');
+                return contentSourceData?.csiDocuments ?? [];
+            },
+            getDocumentById: (documentId) => {
+                const contentSourceData = getContentSourceDataForCurrentInstance('getDocumentById');
+                return contentSourceData?.csiDocumentMap?.[documentId];
+            },
+            getAssets: () => {
+                const contentSourceData = getContentSourceDataForCurrentInstance('getAssets');
+                return contentSourceData?.csiAssets ?? [];
+            },
+            getAssetById: (assetId) => {
+                const contentSourceData = getContentSourceDataForCurrentInstance('getAssetById');
+                return contentSourceData?.csiAssetMap?.[assetId];
+            },
+            updateContent: async (contentChanges: CSITypes.ContentChanges): Promise<void> => {
+                const contentSourceData = getContentSourceDataForCurrentInstance('updateContent');
+                if (!contentSourceData) {
+                    return;
+                }
+                this.logger.debug('content source called updateContent', { contentSourceId });
+                this.pushContentSourceEvent({
+                    eventName: ContentStoreEventType.ContentSourceContentChange,
+                    contentSourceId: contentSourceId,
+                    contentChanges: contentChanges
+                });
+                await this.processContentStoreEvents();
+            },
+
+            invalidateSchema: async () => {
+                const contentSourceData = getContentSourceDataForCurrentInstance('invalidateSchema');
+                if (!contentSourceData) {
+                    return;
+                }
+                this.logger.debug('content source called invalidateSchema', { contentSourceId });
+                this.pushContentSourceEvent({
+                    eventName: ContentStoreEventType.ContentSourceInvalidateSchema,
+                    contentSourceId: contentSourceId
+                });
+                await this.processContentStoreEvents();
+            }
+        };
+
         if (init) {
+            this.userLogger.info(
+                `Initializing content source: ${contentSourceInstance.getContentSourceType()} (project: ${contentSourceInstance.getProjectId()})`
+            );
+            // When stackbit.config.js reloads, it loads new content source instances.
+            // Previously loaded content source instances must be destroyed.
+            const contentSourceData = this.contentSourceDataById[contentSourceId];
+            if (contentSourceData && contentSourceData.instance !== contentSourceInstance) {
+                this.logger.debug('destroy previous content source instance', { contentSourceId });
+                try {
+                    contentSourceData.instance.stopWatchingContentUpdates?.();
+                    await contentSourceData.instance.destroy();
+                } catch (error) {
+                    this.logger.debug('error destroying content source instance', { error });
+                }
+            }
+
+            // If an instance that wasn't destroyed calls one of the InitOptions method don't return any data.
             await contentSourceInstance.init({
                 logger: this.logger,
                 userLogger: this.userLogger,
-                userCommandSpawner: this.userCommandSpawner,
                 localDev: this.localDev,
                 webhookUrl: this.getWebhookUrl(contentSourceInstance.getContentSourceType(), contentSourceInstance.getProjectId()),
+                userCommandSpawner: this.userCommandSpawner,
                 devAppRestartNeeded: this.devAppRestartNeeded,
+                cache: cache,
                 runCommand: this.runCommand,
                 git: this.git
             });
         } else {
-            contentSourceInstance.stopWatchingContentUpdates();
             await contentSourceInstance.reset();
         }
 
-        const csiModels = await contentSourceInstance.getModels();
+        const version = await contentSourceInstance.getVersion();
+        const csiSchema = await contentSourceInstance.getSchema();
+        const csiModels = csiSchema.models;
         const csiModelMap = _.keyBy(csiModels, 'name');
-
-        const locales = await contentSourceInstance.getLocales();
+        const locales = csiSchema.locales;
         const defaultLocaleCode = locales?.find((locale) => locale.default)?.code;
 
+        localCache.csiSchema = csiSchema;
+        localCache.csiModels = csiModels;
+        localCache.csiModelMap = csiModelMap;
+        localCache.locales = locales;
+
         const csiDocuments = await contentSourceInstance.getDocuments({ modelMap: csiModelMap });
-        const csiAssets = await contentSourceInstance.getAssets();
         const csiDocumentMap = _.keyBy(csiDocuments, 'id');
+        localCache.csiDocuments = csiDocuments;
+        localCache.csiDocumentMap = csiDocumentMap;
+
+        const csiAssets = await contentSourceInstance.getAssets();
         const csiAssetMap = _.keyBy(csiAssets, 'id');
+        localCache.csiAssets = csiAssets;
+        localCache.csiAssetMap = csiAssetMap;
 
         const contentStoreAssets = mapCSIAssetsToStoreAssets({
-            csiAssets,
+            csiAssets: csiAssets,
             contentSourceInstance,
             defaultLocaleCode
         });
@@ -471,56 +732,47 @@ export class ContentStore {
         this.logger.debug('loaded content source data', {
             contentSourceId,
             defaultLocaleCode,
-            localesCount: locales.length,
+            localesCount: locales?.length ?? 0,
             modelCount: csiModels.length,
             documentCount: csiDocuments.length,
             assetCount: csiAssets.length
         });
 
-        contentSourceInstance.startWatchingContentUpdates({
-            getModelMap: () => {
-                return csiModelMap;
-            },
-            getDocument({ documentId }: { documentId: string }) {
-                return csiDocumentMap[documentId];
-            },
-            getAsset({ assetId }: { assetId: string }) {
-                return csiAssetMap[assetId];
-            },
-            onContentChange: async (contentChangeEvent: CSITypes.ContentChangeEvent) => {
-                if (this.contentSourceDataById[contentSourceId]?.instance !== contentSourceInstance) {
-                    this.logger.debug('old content source called onContentChange', { contentSourceId });
-                    return;
-                }
-                this.logger.debug('content source called onContentChange.', { contentSourceId });
-                const result = this.onContentChange(contentSourceId, contentChangeEvent);
-
-                this.siteMapEntryGroups = await updateSiteMapEntriesWithContentChanges({
-                    siteMapEntryGroups: this.siteMapEntryGroups,
-                    contentChanges: result,
-                    stackbitConfig: this.stackbitConfig,
-                    contentSourceDataById: this.contentSourceDataById
-                });
-                this.onContentChangeCallback(result);
-            },
-            onSchemaChange: async () => {
-                if (this.contentSourceDataById[contentSourceId]?.instance !== contentSourceInstance) {
-                    this.logger.debug('old content source called onSchemaChange', { contentSourceId });
-                    return;
-                }
-                this.logger.debug('content source called onSchemaChange', { contentSourceId });
-                await this.loadContentSourcesAndProcessData({ init: false, contentSourceIds: [contentSourceId] });
-                this.onSchemaChangeCallback();
-            }
-        });
+        if (init) {
+            this.userLogger.info(
+                `→ Loaded content source data: ${csiModels.length} model${csiModels.length !== 1 ? 's' : ''}, ${csiDocuments.length} document${
+                    csiDocuments.length !== 1 ? 's' : ''
+                } and ${csiAssets.length} asset${csiAssets.length !== 1 ? 's' : ''}`
+            );
+
+            // backward compatibility
+            contentSourceInstance.startWatchingContentUpdates?.({
+                getModelMap: () => {
+                    const contentSourceData = getContentSourceDataForCurrentInstance('getModelMap');
+                    return contentSourceData?.csiModelMap ?? {};
+                },
+                getDocument: ({ documentId }) => {
+                    const contentSourceData = getContentSourceDataForCurrentInstance('getDocument');
+                    return contentSourceData?.csiDocumentMap?.[documentId];
+                },
+                getAsset: ({ assetId }) => {
+                    const contentSourceData = getContentSourceDataForCurrentInstance('getAsset');
+                    return contentSourceData?.csiAssetMap?.[assetId];
+                },
+                onContentChange: cache.updateContent,
+                onSchemaChange: cache.invalidateSchema
+            });
+        }
 
         return {
             id: contentSourceId,
+            version: version,
             srcType: contentSourceInstance.getContentSourceType(),
             srcProjectId: contentSourceInstance.getProjectId(),
             instance: contentSourceInstance,
             locales: locales,
             defaultLocaleCode: defaultLocaleCode,
+            csiSchema: csiSchema,
             csiModels: csiModels,
             csiModelMap: csiModelMap,
             csiDocuments: csiDocuments,
@@ -532,18 +784,26 @@ export class ContentStore {
         };
     }
 
-    private onContentChange(contentSourceId: string, contentChangeEvent: CSITypes.ContentChangeEvent): ContentStoreTypes.ContentChangeResult {
-        // TODO: prevent content change process for contentSourceId if loading content is in progress
-
+    private onContentChange(
+        contentSourceId: string,
+        contentChanges: CSITypes.ContentChanges
+    ): { contentChangeResult: ContentStoreTypes.ContentChangeResult; presetsUpdated: boolean } {
         // certain content changes, like preset changes are interpreted as schema changes
-        let schemaChanged = false;
+        let presetsUpdated = false;
+
+        const contentChangesReq: Required<CSITypes.ContentChanges> = {
+            documents: contentChanges.documents ?? [],
+            assets: contentChanges.assets ?? [],
+            deletedDocumentIds: contentChanges.deletedDocumentIds ?? [],
+            deletedAssetIds: contentChanges.deletedAssetIds ?? []
+        };
 
         this.logger.debug('onContentChange', {
             contentSourceId,
-            documentCount: contentChangeEvent.documents.length,
-            assetCount: contentChangeEvent.assets.length,
-            deletedDocumentCount: contentChangeEvent.deletedDocumentIds.length,
-            deletedAssetCount: contentChangeEvent.deletedAssetIds.length
+            documentCount: contentChangesReq.documents.length,
+            assetCount: contentChangesReq.assets.length,
+            deletedDocumentCount: contentChangesReq.deletedDocumentIds.length,
+            deletedAssetCount: contentChangesReq.deletedAssetIds.length
         });
 
         const result: ContentStoreTypes.ContentChangeResult = {
@@ -556,11 +816,11 @@ export class ContentStore {
         const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
 
         // update contentSourceData with deleted documents
-        contentChangeEvent.deletedDocumentIds.forEach((docId) => {
+        contentChangesReq.deletedDocumentIds.forEach((docId) => {
             // remove preset, make sure there is something to remove first because
             // were explicitly calling onContentChange from deletePreset as well
             if (this.presets[docId] && contentSourceData.csiDocumentMap[docId]?.modelName === StackbitPresetModelName) {
-                schemaChanged = true;
+                presetsUpdated = true;
                 const preset = this.presets[docId]!;
                 const model = contentSourceData.modelMap[preset.modelName];
                 delete this.presets[docId];
@@ -590,7 +850,7 @@ export class ContentStore {
         });
 
         // update contentSourceData with deleted assets
-        contentChangeEvent.deletedAssetIds.forEach((assetId) => {
+        contentChangesReq.deletedAssetIds.forEach((assetId) => {
             // delete document from asset map
             delete contentSourceData.assetMap[assetId];
             delete contentSourceData.csiAssetMap[assetId];
@@ -611,9 +871,9 @@ export class ContentStore {
         });
 
         // map csi documents through stackbitConfig.mapDocuments
-        let mappedDocs = contentChangeEvent.documents;
+        let mappedDocs = contentChangesReq.documents;
         if (this.stackbitConfig?.mapDocuments) {
-            const csiDocumentsWithSource = contentChangeEvent.documents.map(
+            const csiDocumentsWithSource = contentChangesReq.documents.map(
                 (csiDocument): CSITypes.DocumentWithSource => ({
                     srcType: contentSourceData.srcType,
                     srcProjectId: contentSourceData.srcProjectId,
@@ -621,15 +881,13 @@ export class ContentStore {
                 })
             );
 
-            const modelsWithSource = contentSourceData.models.map(
-                (model): CSITypes.ModelWithSource => {
-                    return {
-                        srcType: contentSourceData.srcType,
-                        srcProjectId: contentSourceData.srcProjectId,
-                        ...model
-                    };
-                }
-            );
+            const modelsWithSource = contentSourceData.models.map((model): CSITypes.ModelWithSource => {
+                return {
+                    srcType: contentSourceData.srcType,
+                    srcProjectId: contentSourceData.srcProjectId,
+                    ...model
+                };
+            });
 
             mappedDocs =
                 this.stackbitConfig?.mapDocuments?.({
@@ -643,24 +901,28 @@ export class ContentStore {
             csiDocuments: mappedDocs,
             contentSourceInstance: contentSourceData.instance,
             modelMap: contentSourceData.modelMap,
-            defaultLocaleCode: contentSourceData.defaultLocaleCode
+            defaultLocaleCode: contentSourceData.defaultLocaleCode,
+            createConfigDelegate: getCreateConfigDelegateThunk({
+                getContentSourceDataById: () => this.contentSourceDataById,
+                logger: this.userLogger
+            })
         });
         const assets = mapCSIAssetsToStoreAssets({
-            csiAssets: contentChangeEvent.assets,
+            csiAssets: contentChangesReq.assets,
             contentSourceInstance: contentSourceData.instance,
             defaultLocaleCode: contentSourceData.defaultLocaleCode
         });
 
         // update contentSourceData with new or updated documents and assets
-        Object.assign(contentSourceData.csiDocumentMap, _.keyBy(contentChangeEvent.documents, 'id'));
-        Object.assign(contentSourceData.csiAssetMap, _.keyBy(contentChangeEvent.assets, 'id'));
+        Object.assign(contentSourceData.csiDocumentMap, _.keyBy(contentChangesReq.documents, 'id'));
+        Object.assign(contentSourceData.csiAssetMap, _.keyBy(contentChangesReq.assets, 'id'));
         Object.assign(contentSourceData.documentMap, _.keyBy(documents, 'srcObjectId'));
         Object.assign(contentSourceData.assetMap, _.keyBy(assets, 'srcObjectId'));
 
         for (let idx = 0; idx < documents.length; idx++) {
             // the indexes of mapped documents and documents from changeEvent are the same
             const document = documents[idx]!;
-            const csiDocument = contentChangeEvent.documents[idx]!;
+            const csiDocument = contentChangesReq.documents[idx]!;
             const dataIndex = contentSourceData.documents.findIndex((existingDoc) => existingDoc.srcObjectId === document.srcObjectId);
             if (dataIndex === -1) {
                 contentSourceData.documents.push(document);
@@ -670,7 +932,7 @@ export class ContentStore {
                 contentSourceData.csiDocuments.splice(dataIndex, 1, csiDocument);
             }
             if (csiDocument.modelName === StackbitPresetModelName) {
-                schemaChanged = true;
+                presetsUpdated = true;
                 const preset = getPresetFromDocument({
                     srcType: contentSourceData.srcType,
                     srcProjectId: contentSourceData.srcProjectId,
@@ -696,7 +958,7 @@ export class ContentStore {
         for (let idx = 0; idx < assets.length; idx++) {
             // the indexes of mapped assets and assets from changeEvent are the same
             const asset = assets[idx]!;
-            const csiAsset = contentChangeEvent.assets[idx]!;
+            const csiAsset = contentChangesReq.assets[idx]!;
             const index = contentSourceData.assets.findIndex((existingAsset) => existingAsset.srcObjectId === asset.srcObjectId);
             if (index === -1) {
                 contentSourceData.assets.push(asset);
@@ -713,11 +975,10 @@ export class ContentStore {
             });
         }
 
-        if (schemaChanged) {
-            this.onSchemaChangeCallback?.();
-        }
-
-        return result;
+        return {
+            contentChangeResult: result,
+            presetsUpdated
+        };
     }
 
     private async processData({
@@ -807,15 +1068,13 @@ export class ContentStore {
                 externalModels: csData.csiModels,
                 logger: this.userLogger
             });
-            const modelsWithSource = mergedModels.map(
-                (model): CSITypes.ModelWithSource => {
-                    return {
-                        srcType: csData.srcType,
-                        srcProjectId: csData.srcProjectId,
-                        ...model
-                    };
-                }
-            );
+            const modelsWithSource = mergedModels.map((model): CSITypes.ModelWithSource => {
+                return {
+                    srcType: csData.srcType,
+                    srcProjectId: csData.srcProjectId,
+                    ...model
+                };
+            });
             return accum.concat(modelsWithSource);
         }, []);
 
@@ -852,31 +1111,48 @@ export class ContentStore {
 
         const modelMapByContentSource = groupModelsByContentSource({ models: models });
 
-        const contentSourceDataArr = contentSourceRawDataArr.map(
-            (csData): ContentSourceData => {
-                const modelMap = _.get(modelMapByContentSource, [csData.srcType, csData.srcProjectId], {});
-                const csiDocuments = documentMapByContentSource
-                    ? _.get(documentMapByContentSource, [csData.srcType, csData.srcProjectId], [])
-                    : csData.csiDocuments;
-                const documents = mapCSIDocumentsToStoreDocuments({
-                    csiDocuments: csiDocuments,
-                    contentSourceInstance: csData.instance,
-                    defaultLocaleCode: csData.defaultLocaleCode,
-                    modelMap: modelMap
-                });
-                return {
-                    ...csData,
-                    models: Object.values(modelMap),
-                    modelMap,
-                    documents,
-                    documentMap: _.keyBy(documents, 'srcObjectId')
-                };
-            }
-        );
+        const contentSourceDataArr = contentSourceRawDataArr.map((csData): ContentSourceData => {
+            const modelMap = _.get(modelMapByContentSource, [csData.srcType, csData.srcProjectId], {});
+            const csiDocuments = documentMapByContentSource
+                ? _.get(documentMapByContentSource, [csData.srcType, csData.srcProjectId], [])
+                : csData.csiDocuments;
+            const documents = mapCSIDocumentsToStoreDocuments({
+                csiDocuments: csiDocuments,
+                contentSourceInstance: csData.instance,
+                modelMap: modelMap,
+                defaultLocaleCode: csData.defaultLocaleCode,
+                createConfigDelegate: getCreateConfigDelegateThunk({
+                    getContentSourceDataById: () => this.contentSourceDataById,
+                    logger: this.userLogger
+                })
+            });
+            return {
+                ...csData,
+                models: Object.values(modelMap),
+                modelMap,
+                documents,
+                documentMap: _.keyBy(documents, 'srcObjectId')
+            };
+        });
 
         return _.keyBy(contentSourceDataArr, 'id');
     }
 
+    getContentSourceMeta(): { srcType: string; srcProjectId: string; srcVersion: string; csiVersion: string }[] {
+        return _.reduce(
+            this.contentSourceDataById,
+            (result: { srcType: string; srcProjectId: string; srcVersion: string; csiVersion: string }[], contentSourceData) => {
+                return result.concat({
+                    srcType: contentSourceData.srcType,
+                    srcProjectId: contentSourceData.srcProjectId,
+                    srcVersion: contentSourceData.version.contentSourceVersion,
+                    csiVersion: contentSourceData.version.interfaceVersion
+                });
+            },
+            []
+        );
+    }
+
     getModels(): Record<string, Record<string, Record<string, Model | ImageModel>>> {
         return _.reduce(
             this.contentSourceDataById,
@@ -942,14 +1218,7 @@ export class ContentStore {
                 const srcType = contentSourceData.srcType;
                 const srcProjectId = contentSourceData.srcProjectId;
                 const userContext = getUserContextForSrcType(srcType, user);
-                let result = await contentSourceData.instance.hasAccess({ userContext });
-                // backwards compatibility with older CSI version
-                if (typeof result === 'boolean') {
-                    result = {
-                        hasConnection: result,
-                        hasPermissions: result
-                    };
-                }
+                const result = await contentSourceData.instance.hasAccess({ userContext });
                 return {
                     hasConnection: accum.hasConnection && result.hasConnection,
                     hasPermissions: accum.hasPermissions && result.hasPermissions,
@@ -1091,7 +1360,7 @@ export class ContentStore {
         return contentSourceData.documentMap[srcDocumentId];
     }
 
-    getDocuments({ locale }: { locale?: string }): ContentStoreTypes.Document[] {
+    getDocuments({ locale }: { locale?: string } = {}): ContentStoreTypes.Document[] {
         return _.reduce(
             this.contentSourceDataById,
             (documents: ContentStoreTypes.Document[], contentSourceData) => {
@@ -1124,7 +1393,7 @@ export class ContentStore {
         );
     }
 
-    getLocalizedApiObjects({ locale, objectIds }: { locale?: string, objectIds?: string[] }): ContentStoreTypes.APIObject[] {
+    getLocalizedApiObjects({ locale, objectIds }: { locale?: string; objectIds?: string[] }): ContentStoreTypes.APIObject[] {
         const hasExplicitLocale = !_.isEmpty(locale);
         return _.reduce(
             this.contentSourceDataById,
@@ -1132,18 +1401,16 @@ export class ContentStore {
                 let documents = objectIds
                     ? contentSourceData.documents.filter((document) => objectIds.includes(document.srcObjectId))
                     : contentSourceData.documents;
-                documents = hasExplicitLocale
-                    ? documents.filter((document) => !document.locale || document.locale === locale)
-                    : documents;
-                let assets = objectIds
-                    ? contentSourceData.assets.filter((asset) => objectIds.includes(asset.srcObjectId))
-                    : contentSourceData.assets;
-                assets = hasExplicitLocale
-                    ? assets.filter((asset) => !asset.locale || asset.locale === locale)
-                    : assets;
+                documents = hasExplicitLocale ? documents.filter((document) => !document.locale || document.locale === locale) : documents;
+                let assets = objectIds ? contentSourceData.assets.filter((asset) => objectIds.includes(asset.srcObjectId)) : contentSourceData.assets;
+                assets = hasExplicitLocale ? assets.filter((asset) => !asset.locale || asset.locale === locale) : assets;
                 const currentLocale = locale ?? contentSourceData.defaultLocaleCode;
                 const filteredDocuments = documents.filter((document) => document.srcModelName !== StackbitPresetModelName);
-                const documentObjects = mapDocumentsToLocalizedApiObjects(filteredDocuments, currentLocale);
+                const documentObjects = mapDocumentsToLocalizedApiObjects({
+                    documents: filteredDocuments,
+                    locale: currentLocale,
+                    delegate: createConfigDelegate({ contentSourceDataById: this.contentSourceDataById, logger: this.userLogger })
+                });
                 const imageObjects = mapAssetsToLocalizedApiImages(assets, this.staticAssetsPublicPath, currentLocale);
                 return objects.concat(documentObjects, imageObjects);
             },
@@ -1305,7 +1572,7 @@ export class ContentStore {
                 refProjectId: refProjectId
             });
         }
-        const updatedDocument = await contentSourceData.instance.updateDocument({
+        await contentSourceData.instance.updateDocument({
             document: csiDocument,
             modelMap: csiModelMap,
             userContext: userContext,
@@ -1328,7 +1595,7 @@ export class ContentStore {
                       }
             ]
         });
-        return { srcDocumentId: updatedDocument.id, createdDocumentId: result.srcDocumentId };
+        return { srcDocumentId: srcDocumentId, createdDocumentId: result.srcDocumentId };
     }
 
     async createPreset({
@@ -1380,12 +1647,18 @@ export class ContentStore {
 
         // we delete presets immediately because some CMSs don't notify us
         // when documents have been deleted.
-        this.onContentChange(getContentSourceIdForContentSource(this.presetsContentSource), {
-            documents: [],
-            deletedDocumentIds: [presetId],
-            assets: [],
-            deletedAssetIds: []
+        const contentSourceId = getContentSourceIdForContentSource(this.presetsContentSource);
+        this.pushContentSourceEvent({
+            eventName: ContentStoreEventType.ContentSourceContentChange,
+            contentSourceId: contentSourceId,
+            contentChanges: {
+                documents: [],
+                deletedDocumentIds: [presetId],
+                assets: [],
+                deletedAssetIds: []
+            }
         });
+        await this.processContentStoreEvents();
     }
 
     async uploadAndLinkAsset({
@@ -1453,7 +1726,7 @@ export class ContentStore {
             refType: 'asset',
             refId: result.id
         } as const;
-        const updatedDocument = await contentSourceData.instance.updateDocument({
+        await contentSourceData.instance.updateDocument({
             document: csiDocument,
             modelMap: csiModelMap,
             userContext: userContext,
@@ -1476,7 +1749,7 @@ export class ContentStore {
                       }
             ]
         });
-        return { srcDocumentId: updatedDocument.id };
+        return { srcDocumentId: srcDocumentId };
     }
 
     async createDocument({
@@ -1514,15 +1787,9 @@ export class ContentStore {
             })
         });
 
-        this.logger.debug('created document', { srcType, srcProjectId, srcDocumentId: result.document.id, modelName });
-
-        // do not update cache in contentSourceData.documents and documentMap,
-        // instead wait for contentSource to call onContentChange(contentChangeEvent)
-        // and use data from contentChangeEvent to update the cache
-        // const newDocuments = [result.document, ...result.referencedDocuments];
-        // contentSourceData.documentMap = Object.assign(contentSourceData.documentMap, _.keyBy(newDocuments, 'srcObjectId'));
+        this.logger.debug('created document', { srcType, srcProjectId, srcDocumentId: result.documentId, modelName });
 
-        return { srcDocumentId: result.document.id };
+        return { srcDocumentId: result.documentId };
     }
 
     async updateDocument({
@@ -1558,88 +1825,80 @@ export class ContentStore {
             throw new Error(`error updating document, could not find document model: '${documentModelName}'`);
         }
 
-        const operations = await mapPromise(
-            updateOperations,
-            async (updateOperation): Promise<CSITypes.UpdateOperation> => {
-                const locale = updateOperation.locale ?? contentSourceData.defaultLocaleCode;
-                const modelField = getModelFieldForFieldAtPath(document, model, updateOperation.fieldPath, modelMap, locale);
-                const csiModelField = getModelFieldForFieldAtPath(document, csiModel, updateOperation.fieldPath, csiModelMap, locale);
-                switch (updateOperation.opType) {
-                    case 'set':
-                        const field = await convertOperationField({
-                            operationField: updateOperation.field,
-                            fieldPath: [csiModel.name, ...updateOperation.fieldPath],
-                            modelField,
-                            csiModelField,
-                            modelMap,
-                            csiModelMap,
-                            contentSourceId,
-                            contentSourceDataById: this.contentSourceDataById,
-                            createDocument: getCreateDocumentThunk({
-                                locale: updateOperation.locale,
-                                user
-                            })
-                        });
-                        return {
-                            ...updateOperation,
-                            modelField: csiModelField,
-                            field
-                        };
-                    case 'unset':
-                        return {
-                            ...updateOperation,
-                            modelField: csiModelField
-                        };
-                    case 'insert':
-                        if (modelField.type !== 'list' || csiModelField.type !== 'list') {
-                            throw new Error(`error updating document, 'insert' operation can be performed on 'list' fields only`);
-                        }
-                        const item = await convertOperationField({
-                            operationField: updateOperation.item,
-                            fieldPath: [csiModel.name, ...updateOperation.fieldPath],
-                            modelField: modelField.items,
-                            csiModelField: csiModelField.items,
-                            modelMap,
-                            csiModelMap,
-                            contentSourceId,
-                            contentSourceDataById: this.contentSourceDataById,
-                            createDocument: getCreateDocumentThunk({
-                                locale: updateOperation.locale,
-                                user
-                            })
-                        });
-                        return {
-                            ...updateOperation,
-                            modelField: csiModelField,
-                            item
-                        } as CSITypes.UpdateOperationInsert;
-                    case 'remove':
-                        return {
-                            ...updateOperation,
-                            modelField: csiModelField
-                        };
-                    case 'reorder':
-                        return {
-                            ...updateOperation,
-                            modelField: csiModelField
-                        };
-                }
+        const operations = await mapPromise(updateOperations, async (updateOperation): Promise<CSITypes.UpdateOperation> => {
+            const locale = updateOperation.locale ?? contentSourceData.defaultLocaleCode;
+            const modelField = getModelFieldForFieldAtPath(document, model, updateOperation.fieldPath, modelMap, locale);
+            const csiModelField = getModelFieldForFieldAtPath(document, csiModel, updateOperation.fieldPath, csiModelMap, locale);
+            switch (updateOperation.opType) {
+                case 'set':
+                    const field = await convertOperationField({
+                        operationField: updateOperation.field,
+                        fieldPath: [csiModel.name, ...updateOperation.fieldPath],
+                        modelField,
+                        csiModelField,
+                        modelMap,
+                        csiModelMap,
+                        contentSourceId,
+                        contentSourceDataById: this.contentSourceDataById,
+                        createDocument: getCreateDocumentThunk({
+                            locale: updateOperation.locale,
+                            user
+                        })
+                    });
+                    return {
+                        ...updateOperation,
+                        modelField: csiModelField,
+                        field
+                    };
+                case 'unset':
+                    return {
+                        ...updateOperation,
+                        modelField: csiModelField
+                    };
+                case 'insert':
+                    if (modelField.type !== 'list' || csiModelField.type !== 'list') {
+                        throw new Error(`error updating document, 'insert' operation can be performed on 'list' fields only`);
+                    }
+                    const item = await convertOperationField({
+                        operationField: updateOperation.item,
+                        fieldPath: [csiModel.name, ...updateOperation.fieldPath],
+                        modelField: modelField.items,
+                        csiModelField: csiModelField.items,
+                        modelMap,
+                        csiModelMap,
+                        contentSourceId,
+                        contentSourceDataById: this.contentSourceDataById,
+                        createDocument: getCreateDocumentThunk({
+                            locale: updateOperation.locale,
+                            user
+                        })
+                    });
+                    return {
+                        ...updateOperation,
+                        modelField: csiModelField,
+                        item
+                    } as CSITypes.UpdateOperationInsert;
+                case 'remove':
+                    return {
+                        ...updateOperation,
+                        modelField: csiModelField
+                    };
+                case 'reorder':
+                    return {
+                        ...updateOperation,
+                        modelField: csiModelField
+                    };
             }
-        );
+        });
 
-        const updatedDocumentResult = await contentSourceData.instance.updateDocument({
+        await contentSourceData.instance.updateDocument({
             document: csiDocument,
             modelMap: csiModelMap,
             userContext,
             operations
         });
 
-        // do not update cache in contentSourceData.documents and documentMap,
-        // instead wait for contentSource to call onContentChange(contentChangeEvent)
-        // and use data from contentChangeEvent to update the cache
-        // contentSourceData.documentMap = Object.assign(contentSourceData.documentMap, { [document.srcObjectId]: document });
-
-        return { srcDocumentId: updatedDocumentResult.id };
+        return { srcDocumentId: srcDocumentId };
     }
 
     async duplicateDocument({
@@ -1666,7 +1925,6 @@ export class ContentStore {
             throw new Error(`no document with id '${srcDocumentId}' was found in ${contentSourceData.id}`);
         }
         const modelMap = contentSourceData.modelMap;
-        const csiModelMap = contentSourceData.csiModelMap;
         const model = modelMap[document.srcModelName];
         if (!model) {
             throw new Error(`no model with name '${document.srcModelName}' was found`);
@@ -1696,9 +1954,9 @@ export class ContentStore {
             })
         });
 
-        this.logger.debug('duplicated document', { srcType, srcProjectId, srcDocumentId, newDocumentId: result.document.id, modelName: model.name });
+        this.logger.debug('duplicated document', { srcType, srcProjectId, srcDocumentId, newDocumentId: result.documentId, modelName: model.name });
 
-        return { srcDocumentId: result.document.id };
+        return { srcDocumentId: result.documentId };
     }
 
     async uploadAssets({
@@ -1770,11 +2028,6 @@ export class ContentStore {
             throw new Error(`no document with id '${srcDocumentId}' was found in ${contentSourceData.id}`);
         }
         await contentSourceData.instance.deleteDocument({ document: csiDocument, userContext });
-
-        // do not update cache in contentSourceData.documents and documentMap,
-        // instead wait for contentSource to call onContentChange(contentChangeEvent)
-        // and use data from contentChangeEvent to update the cache
-        // delete contentSourceData.documentMap[srcDocumentId];
     }
 
     async validateDocuments({