@stackbit/cms-core 0.0.15 → 0.0.18-alpha.0

package/src/content-store.ts

@@ -0,0 +1,2112 @@
+import _ from 'lodash';
+import slugify from 'slugify';
+import path from 'path';
+import sanitizeFilename from 'sanitize-filename';
+import {
+    Config,
+    extendConfig,
+    Field,
+    FieldList,
+    FieldListItems,
+    FieldListProps,
+    FieldModelProps,
+    FieldObjectProps,
+    FieldSpecificProps,
+    loadConfigFromDir,
+    Model
+} from '@stackbit/sdk';
+import { mapPromise, omitByNil } from '@stackbit/utils';
+import * as ContentSourceTypes from './content-source-interface';
+import { isLocalizedField } from './content-source-interface';
+import * as ContentStoreTypes from './content-store-types';
+import { IMAGE_MODEL } from './common/common-schema';
+import { Timer } from './utils/timer';
+
+export interface ContentSourceOptions {
+    logger: ContentStoreTypes.Logger;
+    userLogger: ContentStoreTypes.Logger;
+    localDev: boolean;
+    stackbitYamlDir: string;
+    contentSources: ContentSourceTypes.ContentSourceInterface[];
+    onSchemaChangeCallback: () => void;
+    onContentChangeCallback: (contentChanges: ContentStoreTypes.ContentChangeResult) => void;
+    handleConfigAssets: (config: Config) => Promise<Config>;
+}
+
+interface ContentSourceData {
+    id: string;
+    instance: ContentSourceTypes.ContentSourceInterface;
+    type: string;
+    projectId: string;
+    models: Model[];
+    modelMap: Record<string, Model>;
+    locales?: ContentSourceTypes.Locale[];
+    defaultLocaleCode?: string;
+    documents: ContentStoreTypes.Document[];
+    documentMap: Record<string, ContentStoreTypes.Document>;
+    assets: ContentStoreTypes.Asset[];
+    assetMap: Record<string, ContentStoreTypes.Asset>;
+}
+
+export class ContentStore {
+    private readonly contentSources: ContentSourceTypes.ContentSourceInterface[];
+    private readonly logger: ContentStoreTypes.Logger;
+    private readonly userLogger: ContentStoreTypes.Logger;
+    private readonly localDev: boolean;
+    private readonly stackbitYamlDir: string; // TODO: remove stackbitYamlDir, ContentStore should not be aware of filesystem, instead pass autoreloading Config object
+    private readonly onSchemaChangeCallback: () => void;
+    private readonly onContentChangeCallback: (contentChanges: ContentStoreTypes.ContentChangeResult) => void;
+    private readonly handleConfigAssets: (config: Config) => Promise<Config>;
+    private contentSourceDataById: Record<string, ContentSourceData> = {};
+    private contentUpdatesWatchTimer: Timer;
+    private rawStackbitConfig: any;
+    private presets?: Record<string, any>;
+
+    constructor(options: ContentSourceOptions) {
+        this.logger = options.logger.createLogger({ label: 'content-store' });
+        this.userLogger = options.userLogger.createLogger({ label: 'content-store' });
+        this.localDev = options.localDev;
+        this.stackbitYamlDir = options.stackbitYamlDir; // TODO: remove stackbitYamlDir, ContentStore should not be aware of filesystem, instead pass autoreloading Config object
+        this.contentSources = options.contentSources;
+        this.onSchemaChangeCallback = options.onSchemaChangeCallback;
+        this.onContentChangeCallback = options.onContentChangeCallback;
+        this.handleConfigAssets = options.handleConfigAssets;
+        this.contentUpdatesWatchTimer = new Timer({ timerCallback: () => this.handleTimerTimeout(), logger: this.logger });
+    }
+
+    async init(): Promise<void> {
+        this.logger.debug('init');
+        this.rawStackbitConfig = await this.loadStackbitConfig();
+
+        this.logger.debug('init => load content source data');
+        for (const contentSourceInstance of this.contentSources) {
+            await this.loadContentSourceData({ contentSourceInstance, init: true });
+        }
+
+        this.contentUpdatesWatchTimer.startTimer();
+    }
+
+    async reset() {
+        this.logger.debug('reset');
+
+        this.contentUpdatesWatchTimer.stopTimer();
+        this.rawStackbitConfig = await this.loadStackbitConfig();
+
+        this.logger.debug('reset => load content source data');
+        for (const contentSourceInstance of this.contentSources) {
+            await this.loadContentSourceData({ contentSourceInstance, init: false });
+        }
+
+        this.contentUpdatesWatchTimer.startTimer();
+    }
+
+    /**
+     * This method is called when contentUpdatesWatchTimer receives timeout.
+     * It then notifies all content sources to stop watching for content changes.
+     */
+    handleTimerTimeout() {
+        for (const contentSourceInstance of this.contentSources) {
+            contentSourceInstance.stopWatchingContentUpdates();
+        }
+    }
+
+    /**
+     * This method is called when user interacts with Stackbit application.
+     * It is used to reset contentUpdatesWatchTimer. When the timer is over
+     * all content sources are notified to stop watching for content updates.
+     */
+    async keepAlive() {
+        if (!this.contentUpdatesWatchTimer.isRunning()) {
+            this.logger.debug('keepAlive => contentUpdatesWatchTimer is not running => load content source data');
+            for (const contentSourceInstance of this.contentSources) {
+                await this.loadContentSourceData({ contentSourceInstance, init: false });
+            }
+        }
+        this.contentUpdatesWatchTimer.resetTimer();
+    }
+
+    /**
+     * This method is called when a content source notifies Stackbit of models
+     * changes via webhook. When this happens, all content source data
+     *
+     * For example, Contentful notifies Stackbit of any content-type changes via
+     * special webhook.
+     *
+     * @param contentSourceId
+     */
+    async onContentSourceSchemaChange({ contentSourceId }: { contentSourceId: string }) {
+        this.logger.debug('onContentSourceSchemaChange', { contentSourceId });
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        await this.loadContentSourceData({
+            contentSourceInstance: contentSourceData.instance,
+            init: false
+        });
+        this.onSchemaChangeCallback();
+    }
+
+    async onFilesChange(
+        updatedFiles: string[]
+    ): Promise<{ stackbitConfigUpdated?: boolean; schemaChanged?: boolean; contentChanges: ContentStoreTypes.ContentChangeResult }> {
+        this.logger.debug('onFilesChange');
+
+        const stackbitConfigUpdated = _.some(updatedFiles, (filePath) => isStackbitConfigFile(filePath));
+        this.logger.debug(`stackbitConfigUpdated: ${stackbitConfigUpdated}`);
+        if (stackbitConfigUpdated) {
+            this.rawStackbitConfig = await this.loadStackbitConfig();
+        }
+
+        let someContentSourceSchemaUpdated = false;
+        const contentChanges: ContentStoreTypes.ContentChangeResult = {
+            updatedDocuments: [],
+            updatedAssets: [],
+            deletedDocuments: [],
+            deletedAssets: []
+        };
+
+        for (const contentSourceInstance of this.contentSources) {
+            const contentSourceId = getContentSourceIdForContentSource(contentSourceInstance);
+            this.logger.debug(`call onFilesChange for contentSource: ${contentSourceId}`);
+            const { schemaChanged, contentChangeEvent } = contentSourceInstance.onFilesChange?.({ updatedFiles: updatedFiles }) ?? {};
+            this.logger.debug(`schemaChanged: ${schemaChanged}, has contentChangeEvent: ${!!contentChangeEvent}`);
+            // if schema is changed, there is no need to return contentChanges
+            // because schema changes reloads everything and implies content changes
+            if (stackbitConfigUpdated || schemaChanged) {
+                if (schemaChanged) {
+                    someContentSourceSchemaUpdated = true;
+                }
+                await this.loadContentSourceData({ contentSourceInstance, init: false });
+            } else if (contentChangeEvent) {
+                const contentChangeResult = this.onContentChange(contentSourceId, contentChangeEvent);
+                contentChanges.updatedDocuments = contentChanges.updatedDocuments.concat(contentChangeResult.updatedDocuments);
+                contentChanges.updatedAssets = contentChanges.updatedAssets.concat(contentChangeResult.updatedAssets);
+                contentChanges.deletedDocuments = contentChanges.deletedDocuments.concat(contentChangeResult.deletedDocuments);
+                contentChanges.deletedAssets = contentChanges.deletedAssets.concat(contentChangeResult.deletedAssets);
+            }
+        }
+
+        return {
+            stackbitConfigUpdated,
+            schemaChanged: someContentSourceSchemaUpdated || stackbitConfigUpdated,
+            contentChanges: contentChanges
+        };
+    }
+
+    async loadStackbitConfig() {
+        this.logger.debug('loadStackbitConfig');
+        // TODO: use esbuild to watch for stackbit.config.js changes and notify
+        //  the content-store via onStackbitConfigChange with updated rawConfig
+        const { config, errors } = await loadConfigFromDir({ dirPath: this.stackbitYamlDir });
+        for (const error of errors) {
+            this.userLogger.warn(error.message);
+        }
+        if (!config) {
+            this.userLogger.error(`could not load stackbit config`);
+        }
+        return config;
+    }
+
+    async loadContentSourceData({ contentSourceInstance, init }: { contentSourceInstance: ContentSourceTypes.ContentSourceInterface; init: boolean }) {
+        // TODO: defer loading content if content is already loading for a specific content source
+
+        // TODO: optimize: cache raw responses from contentSource
+        //  e.g.: getModels(), getDocuments(), getAssets()
+        //  ana use the cached response to remap documents when only stackbitConfig changes
+
+        const contentSourceId = getContentSourceIdForContentSource(contentSourceInstance);
+        this.logger.debug('loadContentSourceData', { contentSourceId, init });
+
+        if (init) {
+            await contentSourceInstance.init({
+                logger: this.logger,
+                userLogger: this.userLogger,
+                localDev: this.localDev
+            });
+        } else {
+            contentSourceInstance.stopWatchingContentUpdates();
+            await contentSourceInstance.reset();
+        }
+
+        const csModels = await contentSourceInstance.getModels();
+        const locales = await contentSourceInstance?.getLocales();
+        const result = await extendConfig({ dirPath: this.stackbitYamlDir, config: this.rawStackbitConfig, externalModels: csModels });
+        const config = await this.handleConfigAssets(result.config);
+        const models = config.models;
+        const modelMap = _.keyBy(models, 'name');
+        const defaultLocaleCode = locales?.find((locale) => locale.default)?.code;
+
+        for (const error of result.errors) {
+            this.userLogger.warn(error.message);
+        }
+
+        // TODO: load presets externally from config, and create additional map
+        //  that maps presetIds by model name instead of storing that map inside every model
+        this.presets = config.presets;
+
+        const documents = await contentSourceInstance.getDocuments({ modelMap });
+        const assets = await contentSourceInstance.getAssets();
+        const contentStoreDocuments = mapSourceDocumentsToStoreDocuments({
+            documents,
+            contentSourceInstance,
+            modelMap,
+            defaultLocaleCode
+        });
+        const contentStoreAssets = mapSourceAssetsToStoreAssets({
+            assets,
+            contentSourceInstance,
+            defaultLocaleCode
+        });
+
+        this.logger.debug('loaded content source data', {
+            contentSourceId,
+            locales,
+            defaultLocaleCode,
+            modelCount: models.length,
+            documentCount: contentStoreDocuments.length,
+            assetCount: contentStoreAssets.length
+        });
+
+        this.contentSourceDataById[contentSourceId] = {
+            id: contentSourceId,
+            type: contentSourceInstance.getContentSourceType(),
+            projectId: contentSourceInstance.getProjectId(),
+            instance: contentSourceInstance,
+            locales: locales,
+            defaultLocaleCode: defaultLocaleCode,
+            models: models,
+            modelMap: modelMap,
+            documents: contentStoreDocuments,
+            documentMap: _.keyBy(contentStoreDocuments, 'srcObjectId'),
+            assets: contentStoreAssets,
+            assetMap: _.keyBy(contentStoreAssets, 'srcObjectId')
+        };
+
+        contentSourceInstance.startWatchingContentUpdates({
+            getModelMap: () => {
+                const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+                return contentSourceData.modelMap;
+            },
+            onContentChange: (contentChangeEvent: ContentSourceTypes.ContentChangeEvent) => {
+                this.logger.debug('content source called onContentChange', { contentSourceId });
+                const result = this.onContentChange(contentSourceId, contentChangeEvent);
+                this.onContentChangeCallback(result);
+            },
+            onSchemaChange: async () => {
+                this.logger.debug('content source called onSchemaChange', { contentSourceId });
+                await this.loadContentSourceData({
+                    contentSourceInstance: contentSourceInstance,
+                    init: false
+                });
+                this.onSchemaChangeCallback();
+            }
+        });
+    }
+
+    onContentChange(contentSourceId: string, contentChangeEvent: ContentSourceTypes.ContentChangeEvent): ContentStoreTypes.ContentChangeResult {
+        // TODO: prevent content change process for contentSourceId if loading content is in progress
+
+        this.logger.debug('onContentChange', {
+            contentSourceId,
+            documentCount: contentChangeEvent.documents.length,
+            assetCount: contentChangeEvent.assets.length,
+            deletedDocumentCount: contentChangeEvent.deletedDocumentIds.length,
+            deletedAssetCount: contentChangeEvent.deletedAssetIds.length
+        });
+
+        const result: ContentStoreTypes.ContentChangeResult = {
+            updatedDocuments: [],
+            updatedAssets: [],
+            deletedDocuments: [],
+            deletedAssets: []
+        };
+
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        contentChangeEvent.deletedDocumentIds.forEach((docId) => {
+            delete contentSourceData.documentMap[docId];
+            const index = contentSourceData.documents.findIndex((document) => document.srcObjectId === docId);
+            if (index !== -1) {
+                contentSourceData.documents.splice(index, 1);
+            }
+            result.deletedDocuments.push({
+                srcType: contentSourceData.type,
+                srcProjectId: contentSourceData.projectId,
+                srcObjectId: docId
+            });
+        });
+        contentChangeEvent.deletedAssetIds.forEach((assetId) => {
+            delete contentSourceData.assetMap[assetId];
+            const index = contentSourceData.assets.findIndex((asset) => asset.srcObjectId === assetId);
+            if (index !== -1) {
+                contentSourceData.assets.splice(index, 1);
+            }
+            result.deletedAssets.push({
+                srcType: contentSourceData.type,
+                srcProjectId: contentSourceData.projectId,
+                srcObjectId: assetId
+            });
+        });
+        const documents = mapSourceDocumentsToStoreDocuments({
+            documents: contentChangeEvent.documents,
+            contentSourceInstance: contentSourceData.instance,
+            modelMap: contentSourceData.modelMap,
+            defaultLocaleCode: contentSourceData.defaultLocaleCode
+        });
+        const assets = mapSourceAssetsToStoreAssets({
+            assets: contentChangeEvent.assets,
+            contentSourceInstance: contentSourceData.instance,
+            defaultLocaleCode: contentSourceData.defaultLocaleCode
+        });
+
+        Object.assign(contentSourceData.documentMap, _.keyBy(documents, 'srcObjectId'));
+        Object.assign(contentSourceData.assetMap, _.keyBy(assets, 'srcObjectId'));
+        for (const document of documents) {
+            const index = contentSourceData.documents.findIndex((existingDoc) => existingDoc.srcObjectId === document.srcObjectId);
+            if (index === -1) {
+                contentSourceData.documents.push(document);
+            } else {
+                contentSourceData.documents.splice(index, 1, document);
+            }
+            result.updatedDocuments.push({
+                srcType: contentSourceData.type,
+                srcProjectId: contentSourceData.projectId,
+                srcObjectId: document.srcObjectId
+            });
+        }
+        for (const asset of assets) {
+            const index = contentSourceData.assets.findIndex((existingAsset) => existingAsset.srcObjectId === asset.srcObjectId);
+            if (index === -1) {
+                contentSourceData.assets.push(asset);
+            } else {
+                contentSourceData.assets.splice(index, 1, asset);
+            }
+            result.updatedAssets.push({
+                srcType: contentSourceData.type,
+                srcProjectId: contentSourceData.projectId,
+                srcObjectId: asset.srcObjectId
+            });
+        }
+
+        return result;
+    }
+
+    getModels(): Record<string, Record<string, Record<string, Model>>> {
+        return _.reduce(
+            this.contentSourceDataById,
+            (result: Record<string, Record<string, Record<string, Model>>>, contentSourceData) => {
+                const contentSourceType = contentSourceData.instance.getContentSourceType();
+                const srcProjectId = contentSourceData.instance.getProjectId();
+                _.set(result, [contentSourceType, srcProjectId], contentSourceData.modelMap);
+                return result;
+            },
+            {}
+        );
+    }
+
+    getLocales(): string[] {
+        return _.reduce(
+            this.contentSourceDataById,
+            (result: string[], contentSourceData) => {
+                const locales = (contentSourceData.locales ?? []).map((locale) => locale.code);
+                return result.concat(locales);
+            },
+            []
+        );
+    }
+
+    getPresets(): Record<string, any> {
+        return this.presets ?? {};
+    }
+
+    getContentSourceEnvironment({ srcProjectId, srcType }: { srcProjectId: string; srcType: string }): string {
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        return contentSourceData.instance.getProjectEnvironment();
+    }
+
+    hasAccess({ srcType, srcProjectId, user }: { srcType: string; srcProjectId: string; user?: ContentStoreTypes.User }): Promise<boolean> {
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        const userContext = getUserContextForSrcType(srcType, user);
+        return contentSourceData.instance.hasAccess({ userContext });
+    }
+
+    hasChanges({
+        srcType,
+        srcProjectId,
+        documents
+    }: {
+        srcType?: string;
+        srcProjectId?: string;
+        documents?: { srcType: string; srcProjectId: string; srcObjectId: string }[];
+    }): {
+        hasChanges: boolean;
+        changedObjects: {
+            srcType: string;
+            srcProjectId: string;
+            srcObjectId: string;
+        }[];
+    } {
+        let result: (ContentStoreTypes.Document | ContentStoreTypes.Asset)[];
+        if (srcType && srcProjectId) {
+            const contentSourceId = getContentSourceId(srcType, srcProjectId);
+            const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+            result = [...contentSourceData.documents, ...contentSourceData.assets];
+        } else if (documents && documents.length > 0) {
+            const documentsBySourceId = _.groupBy(documents, (document) => getContentSourceId(document.srcType, document.srcProjectId));
+            result = _.reduce(
+                documentsBySourceId,
+                (result: (ContentStoreTypes.Document | ContentStoreTypes.Asset)[], documents, contentSourceId) => {
+                    const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+                    for (const document of documents) {
+                        if (document.srcObjectId in contentSourceData.documentMap) {
+                            result.push(contentSourceData.documentMap[document.srcObjectId]!);
+                        } else if (document.srcObjectId in contentSourceData.assetMap) {
+                            result.push(contentSourceData.assetMap[document.srcObjectId]!);
+                        }
+                    }
+                    return result;
+                },
+                []
+            );
+        } else {
+            result = _.reduce(
+                this.contentSourceDataById,
+                (result: (ContentStoreTypes.Document | ContentStoreTypes.Asset)[], contentSourceData) => {
+                    return result.concat(contentSourceData.documents, contentSourceData.assets);
+                },
+                []
+            );
+        }
+        const changedDocuments = result.filter((document) => document.status === 'added' || document.status === 'modified');
+        return {
+            hasChanges: !_.isEmpty(changedDocuments),
+            changedObjects: changedDocuments.map((item) => ({
+                srcType: item.srcType,
+                srcProjectId: item.srcProjectId,
+                srcObjectId: item.srcObjectId
+            }))
+        };
+    }
+
+    getDocument({
+        srcDocumentId,
+        srcProjectId,
+        srcType
+    }: {
+        srcDocumentId: string;
+        srcProjectId: string;
+        srcType: string;
+    }): ContentStoreTypes.Document | undefined {
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        return contentSourceData.documentMap[srcDocumentId];
+    }
+
+    getDocuments(): ContentStoreTypes.Document[] {
+        return _.reduce(
+            this.contentSourceDataById,
+            (documents: ContentStoreTypes.Document[], contentSourceData) => {
+                return documents.concat(contentSourceData.documents);
+            },
+            []
+        );
+    }
+
+    getAsset({ srcAssetId, srcProjectId, srcType }: { srcAssetId: string; srcProjectId: string; srcType: string }): ContentStoreTypes.Asset | undefined {
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        return contentSourceData.assetMap[srcAssetId];
+    }
+
+    getAssets(): ContentStoreTypes.Asset[] {
+        return _.reduce(
+            this.contentSourceDataById,
+            (assets: ContentStoreTypes.Asset[], contentSourceData) => {
+                return assets.concat(contentSourceData.assets);
+            },
+            []
+        );
+    }
+
+    getLocalizedApiObjects({ locale }: { locale?: string }): ContentStoreTypes.APIObject[] {
+        return _.reduce(
+            this.contentSourceDataById,
+            (objects: ContentStoreTypes.APIObject[], contentSourceData) => {
+                locale = locale ?? contentSourceData.defaultLocaleCode;
+                const documentObjects = mapDocumentsToLocalizedApiObjects(contentSourceData.documents, locale);
+                const imageObjects = mapAssetsToLocalizedApiImages(contentSourceData.assets, locale);
+                return objects.concat(documentObjects, imageObjects);
+            },
+            []
+        );
+    }
+
+    getApiAssets({
+        srcType,
+        srcProjectId,
+        pageSize = 20,
+        pageNum = 1,
+        searchQuery
+    }: { srcType?: string; srcProjectId?: string; pageSize?: number; pageNum?: number; searchQuery?: string } = {}): {
+        assets: ContentStoreTypes.APIAsset[];
+        pageSize: number;
+        pageNum: number;
+        totalPages: number;
+    } {
+        let assets: ContentStoreTypes.APIAsset[];
+        if (srcProjectId && srcType) {
+            const contentSourceId = getContentSourceId(srcType, srcProjectId);
+            const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+            assets = mapStoreAssetsToAPIAssets(contentSourceData.assets, contentSourceData.defaultLocaleCode);
+        } else {
+            assets = _.reduce(
+                this.contentSourceDataById,
+                (result: ContentStoreTypes.APIAsset[], contentSourceData) => {
+                    const assets = mapStoreAssetsToAPIAssets(contentSourceData.assets, contentSourceData.defaultLocaleCode);
+                    return result.concat(assets);
+                },
+                []
+            );
+        }
+
+        let filteredFiles = assets;
+        if (searchQuery) {
+            const sanitizedSearchQuery = sanitizeFilename(searchQuery).toLowerCase();
+            filteredFiles = assets.filter((asset) => asset.fileName && path.basename(asset.fileName).toLowerCase().includes(sanitizedSearchQuery));
+        }
+        const sortedAssets = _.orderBy(filteredFiles, ['fileName'], ['asc']);
+        const skip = (pageNum - 1) * pageSize;
+        const totalPages = Math.ceil(filteredFiles.length / pageSize);
+        const pagesAssets = sortedAssets.slice(skip, skip + pageSize);
+
+        return {
+            assets: pagesAssets,
+            pageSize: pageSize,
+            pageNum: pageNum,
+            totalPages: totalPages
+        };
+    }
+
+    async createAndLinkDocument({
+        srcType,
+        srcProjectId,
+        srcDocumentId,
+        fieldPath,
+        modelName,
+        object,
+        index,
+        locale,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        srcDocumentId: string;
+        fieldPath: (string | number)[];
+        modelName?: string;
+        object?: Record<string, any>;
+        index?: number;
+        locale?: string;
+        user?: ContentStoreTypes.User;
+    }): Promise<{ srcDocumentId: string }> {
+        this.logger.debug('createAndLinkDocument', { srcType, srcProjectId, srcDocumentId, fieldPath, modelName, index, locale });
+
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+
+        // get the document that is being updated
+        const document = contentSourceData.documentMap[srcDocumentId];
+        if (!document) {
+            throw new Error(`no document with id '${srcDocumentId}' was found in ${contentSourceData.id}`);
+        }
+
+        // get the document model
+        const documentModelName = document.srcModelName;
+        const modelMap = contentSourceData.modelMap;
+        const model = modelMap[documentModelName];
+        if (!model) {
+            throw new Error(`error updating document, could not find document model: '${documentModelName}'`);
+        }
+
+        // get the 'reference' model field in the updated document that will be used to link the new document
+        locale = locale ?? contentSourceData.defaultLocaleCode;
+        const modelField = getModelFieldForFieldAtPath(document, model, fieldPath, modelMap, locale);
+        if (!modelField) {
+            throw Error(`the "fieldPath" points to non existing model field: ${fieldPath.join('.')}`);
+        }
+        const fieldProps = modelField.type === 'list' ? modelField.items! : modelField;
+        if (fieldProps.type !== 'reference') {
+            throw Error(`error in "createAndLinkDocument", this operation can only be used on reference field: ${fieldPath.join('.')}`);
+        }
+
+        // get the model name for the new document
+        if (!modelName && fieldProps.models.length === 1) {
+            modelName = fieldProps.models[0];
+        }
+        if (!modelName) {
+            throw Error(`error in "createAndLinkDocument", missing "modelName": ${fieldPath.join('.')}`);
+        }
+
+        // create the new document
+        const result = await this.createDocument({
+            object: object,
+            srcProjectId: srcProjectId,
+            srcType: srcType,
+            modelName: modelName,
+            locale: locale,
+            user: user
+        });
+
+        // update the document by linking the field to the created document
+        const userContext = getUserContextForSrcType(srcType, user);
+        const field = {
+            type: 'reference',
+            refType: 'document',
+            refId: result.srcDocumentId
+        } as const;
+        const updatedDocument = await contentSourceData.instance.updateDocument({
+            documentId: srcDocumentId,
+            modelMap: modelMap,
+            userContext: userContext,
+            operations: [
+                modelField.type === 'list'
+                    ? {
+                          opType: 'insert',
+                          fieldPath: fieldPath,
+                          modelField: modelField,
+                          locale: locale,
+                          index: index,
+                          item: field
+                      }
+                    : {
+                          opType: 'set',
+                          fieldPath: fieldPath,
+                          modelField: modelField,
+                          locale: locale,
+                          field: field
+                      }
+            ]
+        });
+        return { srcDocumentId: updatedDocument.id };
+    }
+
+    async uploadAndLinkAsset({
+        srcType,
+        srcProjectId,
+        srcDocumentId,
+        fieldPath,
+        asset,
+        index,
+        locale,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        srcDocumentId: string;
+        fieldPath: (string | number)[];
+        asset: ContentStoreTypes.UploadAssetData;
+        index?: number;
+        locale?: string;
+        user?: ContentStoreTypes.User;
+    }): Promise<{ srcDocumentId: string }> {
+        this.logger.debug('uploadAndLinkAsset', { srcType, srcProjectId, srcDocumentId, fieldPath, index, locale });
+
+        // get the document that is being updated
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        const document = contentSourceData.documentMap[srcDocumentId];
+        if (!document) {
+            throw new Error(`no document with id '${srcDocumentId}' was found in ${contentSourceData.id}`);
+        }
+
+        // get the document model
+        const documentModelName = document.srcModelName;
+        const modelMap = contentSourceData.modelMap;
+        const model = modelMap[documentModelName];
+        if (!model) {
+            throw new Error(`error updating document, could not find document model: '${documentModelName}'`);
+        }
+
+        // get the 'reference' model field in the updated document that will be used to link the new asset
+        locale = locale ?? contentSourceData.defaultLocaleCode;
+        const modelField = getModelFieldForFieldAtPath(document, model, fieldPath, modelMap, locale);
+        if (!modelField) {
+            throw Error(`the "fieldPath" points to non existing model field: ${fieldPath.join('.')}`);
+        }
+        const fieldProps = modelField.type === 'list' ? modelField.items! : modelField;
+        if (fieldProps.type !== 'reference' && fieldProps.type !== 'image') {
+            throw Error(`error in "uploadAndLinkAsset", this operation can only be used on reference and image fields: ${fieldPath.join('.')}`);
+        }
+
+        // upload the new asset
+        const userContext = getUserContextForSrcType(srcType, user);
+        const result = await contentSourceData.instance.uploadAsset({
+            url: asset.url,
+            fileName: asset.metadata.name,
+            mimeType: asset.metadata.type,
+            locale: locale,
+            userContext: userContext
+        });
+
+        // update the document by linking the field to the created asset
+        const field = {
+            type: 'reference',
+            refType: 'asset',
+            refId: result.id
+        } as const;
+        const updatedDocument = await contentSourceData.instance.updateDocument({
+            documentId: srcDocumentId,
+            modelMap: modelMap,
+            userContext: userContext,
+            operations: [
+                modelField.type === 'list'
+                    ? {
+                          opType: 'insert',
+                          fieldPath: fieldPath,
+                          modelField: modelField,
+                          locale: locale,
+                          index: index,
+                          item: field
+                      }
+                    : {
+                          opType: 'set',
+                          fieldPath: fieldPath,
+                          modelField: modelField,
+                          locale: locale,
+                          field: field
+                      }
+            ]
+        });
+        return { srcDocumentId: updatedDocument.id };
+    }
+
+    async createDocument({
+        srcType,
+        srcProjectId,
+        modelName,
+        object,
+        locale,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        modelName: string;
+        object?: Record<string, any>;
+        locale?: string;
+        user?: ContentStoreTypes.User;
+    }): Promise<{ srcDocumentId: string }> {
+        this.logger.debug('createDocument', { srcType, srcProjectId, modelName, locale });
+
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        const modelMap = contentSourceData.modelMap;
+        const model = modelMap[modelName];
+        if (!model) {
+            throw new Error(`no model with name '${modelName}' was found`);
+        }
+
+        locale = locale ?? contentSourceData.defaultLocaleCode;
+        const userContext = getUserContextForSrcType(srcType, user);
+        const result = await createDocumentRecursively({
+            object,
+            model,
+            modelMap,
+            locale,
+            userContext,
+            contentSourceInstance: contentSourceData.instance
+        });
+        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'));
+
+        return { srcDocumentId: result.document.id };
+    }
+
+    async updateDocument({
+        srcType,
+        srcProjectId,
+        srcDocumentId,
+        updateOperations,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        srcDocumentId: string;
+        updateOperations: ContentStoreTypes.UpdateOperation[];
+        user?: ContentStoreTypes.User;
+    }): Promise<{ srcDocumentId: string }> {
+        this.logger.debug('updateDocument');
+
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        const modelMap = contentSourceData.modelMap;
+        const userContext = getUserContextForSrcType(srcType, user);
+
+        const operations = await mapPromise(
+            updateOperations,
+            async (updateOperation): Promise<ContentSourceTypes.UpdateOperation> => {
+                const document = contentSourceData.documentMap[srcDocumentId];
+                if (!document) {
+                    throw new Error(`no document with id '${srcDocumentId}' was found in ${contentSourceData.id}`);
+                }
+                const documentModelName = document.srcModelName;
+                const model = modelMap[documentModelName];
+                if (!model) {
+                    throw new Error(`error updating document, could not find document model: '${documentModelName}'`);
+                }
+                const locale = updateOperation.locale ?? contentSourceData.defaultLocaleCode;
+                const modelField = getModelFieldForFieldAtPath(document, model, updateOperation.fieldPath, modelMap, locale);
+                switch (updateOperation.opType) {
+                    case 'set':
+                        const field = await convertOperationField({
+                            operationField: updateOperation.field,
+                            fieldPath: updateOperation.fieldPath,
+                            locale: updateOperation.locale,
+                            modelField,
+                            modelMap,
+                            userContext,
+                            contentSourceInstance: contentSourceData.instance
+                        });
+                        return {
+                            ...updateOperation,
+                            modelField,
+                            field
+                        };
+                    case 'unset':
+                        return { ...updateOperation, modelField };
+                    case 'insert':
+                        const item = await convertOperationField({
+                            operationField: updateOperation.item,
+                            fieldPath: updateOperation.fieldPath,
+                            locale: updateOperation.locale,
+                            modelField,
+                            modelMap,
+                            userContext,
+                            contentSourceInstance: contentSourceData.instance
+                        });
+                        return {
+                            ...updateOperation,
+                            modelField,
+                            item
+                        };
+                    case 'remove':
+                        return { ...updateOperation, modelField };
+                    case 'reorder':
+                        return { ...updateOperation, modelField };
+                }
+            }
+        );
+
+        const document = await contentSourceData.instance.updateDocument({
+            documentId: srcDocumentId,
+            modelMap,
+            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: document.id };
+    }
+
+    async duplicateDocument({
+        srcType,
+        srcProjectId,
+        srcDocumentId,
+        object,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        srcDocumentId: string;
+        object?: Record<string, any>;
+        user?: ContentStoreTypes.User;
+    }): Promise<{ srcDocumentId: string }> {
+        this.logger.debug('duplicateDocument');
+
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        const document = contentSourceData.documentMap[srcDocumentId];
+        if (!document) {
+            throw new Error(`no document with id '${srcDocumentId}' was found in ${contentSourceData.id}`);
+        }
+        const modelMap = contentSourceData.modelMap;
+        const model = modelMap[document.srcModelName];
+        if (!model) {
+            throw new Error(`no model with name '${document.srcModelName}' was found`);
+        }
+
+        const userContext = getUserContextForSrcType(srcType, user);
+        // TODO: handle duplicatable and non duplicatable models
+        // TODO: handle fields from the provided object
+        const documentResult = await contentSourceData.instance.createDocument({
+            documentFields: mapStoreFieldsToSourceFields({
+                documentFields: document.fields,
+                modelFields: model.fields!,
+                modelMap: contentSourceData.modelMap
+            }),
+            model,
+            modelMap,
+            locale: contentSourceData.defaultLocaleCode,
+            userContext
+        });
+
+        return { srcDocumentId: documentResult.id };
+    }
+
+    async uploadAssets({
+        srcType,
+        srcProjectId,
+        assets,
+        locale,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        assets: ContentStoreTypes.UploadAssetData[];
+        locale?: string;
+        user?: ContentStoreTypes.User;
+    }): Promise<ContentStoreTypes.APIAsset[]> {
+        this.logger.debug('uploadAssets');
+
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        const sourceAssets: ContentSourceTypes.Asset[] = [];
+        const userContext = getUserContextForSrcType(srcType, user);
+
+        locale = locale ?? contentSourceData.defaultLocaleCode;
+
+        for (const asset of assets) {
+            let base64 = undefined;
+            if (asset.data) {
+                const matchResult = asset.data.match(/;base64,([\s\S]+)$/);
+                if (matchResult) {
+                    base64 = matchResult[1];
+                }
+            }
+            const sourceAsset = await contentSourceData.instance.uploadAsset({
+                url: asset.url,
+                base64: base64,
+                fileName: asset.metadata.name,
+                mimeType: asset.metadata.type,
+                locale: locale,
+                userContext: userContext
+            });
+            sourceAssets.push(sourceAsset);
+        }
+        const storeAssets = mapSourceAssetsToStoreAssets({
+            assets: sourceAssets,
+            contentSourceInstance: contentSourceData.instance,
+            defaultLocaleCode: contentSourceData.defaultLocaleCode
+        });
+        return mapStoreAssetsToAPIAssets(storeAssets, locale);
+    }
+
+    async deleteDocument({
+        srcType,
+        srcProjectId,
+        srcDocumentId,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        srcDocumentId: string;
+        user?: ContentStoreTypes.User;
+    }) {
+        this.logger.debug('deleteDocument');
+
+        const userContext = getUserContextForSrcType(srcType, user);
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        await contentSourceData.instance.deleteDocument({ documentId: srcDocumentId, 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({
+        objects,
+        locale,
+        user
+    }: {
+        objects: { srcType: string; srcProjectId: string; srcObjectId: string }[];
+        locale?: string;
+        user?: ContentStoreTypes.User;
+    }): Promise<{ errors: ContentStoreTypes.ValidationError[] }> {
+        this.logger.debug('validateDocuments');
+
+        const objectsBySourceId = _.groupBy(objects, (object) => getContentSourceId(object.srcType, object.srcProjectId));
+        let errors: ContentStoreTypes.ValidationError[] = [];
+        for (const [contentSourceId, objects] of Object.entries(objectsBySourceId)) {
+            const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+            locale = locale ?? contentSourceData.defaultLocaleCode;
+            const documentIds = [];
+            const assetIds = [];
+            for (const object of objects) {
+                if (object.srcObjectId in contentSourceData.documentMap) {
+                    documentIds.push(object.srcObjectId);
+                } else if (object.srcObjectId in contentSourceData.assetMap) {
+                    assetIds.push(object.srcObjectId);
+                }
+            }
+            const userContext = getUserContextForSrcType(contentSourceData.type, user);
+            const validationResult = await contentSourceData.instance.validateDocuments({ documentIds, assetIds, locale, userContext });
+            errors = errors.concat(
+                validationResult.errors.map((validationError) => ({
+                    message: validationError.message,
+                    srcType: contentSourceData.type,
+                    srcProjectId: contentSourceData.projectId,
+                    srcObjectType: validationError.objectType,
+                    srcObjectId: validationError.objectId,
+                    fieldPath: validationError.fieldPath,
+                    isUniqueValidation: validationError.isUniqueValidation
+                }))
+            );
+        }
+
+        return { errors };
+
+        /* validate for multiple sources
+        const objectsBySourceId = _.groupBy(objects, (document) => getContentSourceId(document.srcType, document.srcProjectId));
+        const contentSourceIds = Object.keys(objectsBySourceId);
+        return reducePromise(
+            contentSourceIds,
+            async (result: ContentStoreTypes.ValidationError[], contentSourceId) => {
+                const documents = documentsBySourceId[contentSourceId]!;
+                const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+                const validationErrors = await contentSourceData.instance.validateDocuments({ documentIds: documents.map((document) => document.srcObjectId) });
+                return result.concat(validationErrors);
+            },
+            []
+        );
+         */
+    }
+
+    async publishDocuments({ objects, user }: { objects: { srcType: string; srcProjectId: string; srcObjectId: string }[]; user?: ContentStoreTypes.User }) {
+        this.logger.debug('publishDocuments');
+
+        const objectsBySourceId = _.groupBy(objects, (object) => getContentSourceId(object.srcType, object.srcProjectId));
+        for (const [contentSourceId, objects] of Object.entries(objectsBySourceId)) {
+            const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+            const userContext = getUserContextForSrcType(contentSourceData.type, user);
+            const documentIds = [];
+            const assetIds = [];
+            for (const object of objects) {
+                if (object.srcObjectId in contentSourceData.documentMap) {
+                    documentIds.push(object.srcObjectId);
+                } else if (object.srcObjectId in contentSourceData.assetMap) {
+                    assetIds.push(object.srcObjectId);
+                }
+            }
+            await contentSourceData.instance.publishDocuments({ documentIds, assetIds, userContext });
+        }
+    }
+
+    private getContentSourceDataByIdOrThrow(contentSourceId: string): ContentSourceData {
+        const contentSourceData = this.contentSourceDataById[contentSourceId];
+        if (!contentSourceData) {
+            throw new Error(`no content source for id '${contentSourceId}' was found`);
+        }
+        return contentSourceData;
+    }
+}
+
+export function getContentSourceId(contentSourceType: string, srcProjectId: string) {
+    return contentSourceType + ':' + srcProjectId;
+}
+
+function getUserContextForSrcType(srcType: string, user?: ContentStoreTypes.User): unknown {
+    return user?.connections?.find((connection) => connection.type === srcType);
+}
+
+function mapSourceAssetsToStoreAssets({
+    assets,
+    contentSourceInstance,
+    defaultLocaleCode
+}: {
+    assets: ContentSourceTypes.Asset[];
+    contentSourceInstance: ContentSourceTypes.ContentSourceInterface;
+    defaultLocaleCode?: string;
+}): ContentStoreTypes.Asset[] {
+    const extra = {
+        srcType: contentSourceInstance.getContentSourceType(),
+        srcProjectId: contentSourceInstance.getProjectId(),
+        srcProjectUrl: contentSourceInstance.getProjectManageUrl(),
+        srcEnvironment: contentSourceInstance.getProjectEnvironment()
+    };
+    return assets.map((asset) => sourceAssetToStoreAsset({ asset, defaultLocaleCode, extra }));
+}
+
+function sourceAssetToStoreAsset({
+    asset,
+    defaultLocaleCode,
+    extra
+}: {
+    asset: ContentSourceTypes.Asset;
+    defaultLocaleCode?: string;
+    extra: { srcType: string; srcProjectId: string; srcProjectUrl: string; srcEnvironment: string };
+}): ContentStoreTypes.Asset {
+    return {
+        type: 'asset',
+        ...extra,
+        srcObjectId: asset.id,
+        srcObjectUrl: asset.manageUrl,
+        srcObjectLabel: getObjectLabel(asset.fields, IMAGE_MODEL, defaultLocaleCode),
+        srcModelName: IMAGE_MODEL.name,
+        srcModelLabel: IMAGE_MODEL.label!,
+        isChanged: asset.status === 'added' || asset.status === 'modified',
+        status: asset.status,
+        createdAt: asset.createdAt,
+        createdBy: asset.createdBy,
+        updatedAt: asset.updatedAt,
+        updatedBy: asset.updatedBy,
+        fields: {
+            title: {
+                label: 'Title',
+                ...asset.fields.title
+            },
+            file: {
+                label: 'File',
+                ...asset.fields.file
+            }
+        }
+    };
+}
+
+function mapSourceDocumentsToStoreDocuments({
+    documents,
+    contentSourceInstance,
+    modelMap,
+    defaultLocaleCode
+}: {
+    documents: ContentSourceTypes.Document[];
+    contentSourceInstance: ContentSourceTypes.ContentSourceInterface;
+    modelMap: Record<string, Model>;
+    defaultLocaleCode?: string;
+}): ContentStoreTypes.Document[] {
+    const extra = {
+        srcType: contentSourceInstance.getContentSourceType(),
+        srcProjectId: contentSourceInstance.getProjectId(),
+        srcProjectUrl: contentSourceInstance.getProjectManageUrl(),
+        srcEnvironment: contentSourceInstance.getProjectEnvironment()
+    };
+    return documents.map((document) =>
+        mapSourceDocumentToStoreDocument({ document, model: modelMap[document.modelName]!, modelMap, defaultLocaleCode, extra })
+    );
+}
+
+function mapSourceDocumentToStoreDocument({
+    document,
+    model,
+    modelMap,
+    defaultLocaleCode,
+    extra
+}: {
+    document: ContentSourceTypes.Document;
+    model: Model;
+    modelMap: Record<string, Model>;
+    defaultLocaleCode?: string;
+    extra: { srcType: string; srcProjectId: string; srcProjectUrl: string; srcEnvironment: string };
+}): ContentStoreTypes.Document {
+    return {
+        type: 'document',
+        ...extra,
+        srcObjectId: document.id,
+        srcObjectUrl: document.manageUrl,
+        srcObjectLabel: getObjectLabel(document.fields, model, defaultLocaleCode),
+        srcModelLabel: model.label ?? _.startCase(document.modelName),
+        srcModelName: document.modelName,
+        isChanged: document.status === 'added' || document.status === 'modified',
+        status: document.status,
+        createdAt: document.createdAt,
+        createdBy: document.createdBy,
+        updatedAt: document.updatedAt,
+        updatedBy: document.updatedBy,
+        fields: mapSourceFieldsToStoreFields({
+            documentFields: document.fields,
+            modelFields: model.fields ?? [],
+            modelMap,
+            defaultLocaleCode
+        })
+    };
+}
+
+function mapSourceFieldsToStoreFields({
+    documentFields,
+    modelFields,
+    modelMap,
+    defaultLocaleCode
+}: {
+    documentFields: Record<string, ContentSourceTypes.DocumentField>;
+    modelFields: Field[];
+    modelMap: Record<string, Model>;
+    defaultLocaleCode?: string;
+}): Record<string, ContentStoreTypes.DocumentField> {
+    return modelFields.reduce((result: Record<string, ContentStoreTypes.DocumentField>, modelField) => {
+        const documentField = documentFields[modelField.name];
+        const docField = mapSourceFieldToStoreField({
+            documentField,
+            modelField,
+            modelMap,
+            defaultLocaleCode
+        });
+        docField.label = modelField.label;
+        result[modelField.name] = docField;
+        return result;
+    }, {});
+}
+
+function mapSourceFieldToStoreField({
+    documentField,
+    modelField,
+    modelMap,
+    defaultLocaleCode
+}: {
+    documentField: ContentSourceTypes.DocumentField | undefined;
+    modelField: FieldSpecificProps;
+    modelMap: Record<string, Model>;
+    defaultLocaleCode?: string;
+}): ContentStoreTypes.DocumentField {
+    if (!documentField) {
+        const isUnset = ['object', 'model', 'reference', 'richText', 'markdown', 'image', 'file', 'json'].includes(modelField.type);
+        return {
+            type: modelField.type,
+            ...(isUnset ? { isUnset } : null),
+            ...(modelField.type === 'list' ? { items: [] } : null)
+        } as ContentStoreTypes.DocumentField;
+    }
+    // TODO: check if need to add "options" to "enum" and subtype/min/max to "number"
+    switch (modelField.type) {
+        case 'object':
+            return mapObjectField(documentField as ContentSourceTypes.DocumentFieldForType<typeof modelField.type>, modelField, modelMap, defaultLocaleCode);
+        case 'model':
+            return mapModelField(documentField as ContentSourceTypes.DocumentModelField, modelField, modelMap, defaultLocaleCode);
+        case 'list':
+            return mapListField(documentField as ContentSourceTypes.DocumentListField, modelField, modelMap, defaultLocaleCode);
+        case 'richText':
+            return mapRichTextField(documentField as ContentSourceTypes.DocumentRichTextField);
+        case 'markdown':
+            return mapMarkdownField(documentField as ContentSourceTypes.DocumentValueField);
+        default:
+            return documentField as ContentStoreTypes.DocumentField;
+    }
+}
+
+function mapObjectField(
+    documentField: ContentSourceTypes.DocumentObjectField,
+    modelField: FieldObjectProps,
+    modelMap: Record<string, Model>,
+    defaultLocaleCode?: string
+): ContentStoreTypes.DocumentObjectField {
+    if (!isLocalizedField(documentField)) {
+        return {
+            type: documentField.type,
+            srcObjectLabel: getObjectLabel(documentField.fields ?? {}, modelField ?? [], defaultLocaleCode),
+            fields: mapSourceFieldsToStoreFields({
+                documentFields: documentField.fields ?? {},
+                modelFields: modelField.fields ?? [],
+                modelMap,
+                defaultLocaleCode
+            })
+        };
+    }
+    return {
+        type: documentField.type,
+        localized: true,
+        locales: _.mapValues(documentField.locales, (locale) => {
+            return {
+                locale: locale.locale,
+                srcObjectLabel: getObjectLabel(locale.fields ?? {}, modelField, locale.locale),
+                fields: mapSourceFieldsToStoreFields({
+                    documentFields: locale.fields ?? {},
+                    modelFields: modelField.fields ?? [],
+                    modelMap,
+                    defaultLocaleCode
+                })
+            };
+        })
+    };
+}
+
+function mapModelField(
+    documentField: ContentSourceTypes.DocumentModelField,
+    modelField: FieldModelProps,
+    modelMap: Record<string, Model>,
+    defaultLocaleCode?: string
+): ContentStoreTypes.DocumentModelField {
+    if (!isLocalizedField(documentField)) {
+        const model = modelMap[documentField.modelName]!;
+        return {
+            type: documentField.type,
+            srcObjectLabel: getObjectLabel(documentField.fields ?? {}, model, defaultLocaleCode),
+            srcModelName: documentField.modelName,
+            srcModelLabel: model.label ?? _.startCase(model.name),
+            fields: mapSourceFieldsToStoreFields({
+                documentFields: documentField.fields ?? {},
+                modelFields: model.fields ?? [],
+                modelMap,
+                defaultLocaleCode
+            })
+        };
+    }
+    return {
+        type: documentField.type,
+        localized: true,
+        locales: _.mapValues(documentField.locales, (locale) => {
+            const model = modelMap[locale.modelName]!;
+            return {
+                locale: locale.locale,
+                srcObjectLabel: getObjectLabel(locale.fields ?? {}, model, locale.locale),
+                srcModelName: locale.modelName,
+                srcModelLabel: model.label ?? _.startCase(model.name),
+                fields: mapSourceFieldsToStoreFields({
+                    documentFields: locale.fields ?? {},
+                    modelFields: model.fields ?? [],
+                    modelMap,
+                    defaultLocaleCode
+                })
+            };
+        })
+    };
+}
+
+function mapListField(
+    documentField: ContentSourceTypes.DocumentListField,
+    modelField: FieldListProps,
+    modelMap: Record<string, Model>,
+    defaultLocaleCode?: string
+): ContentStoreTypes.DocumentListField {
+    if (!isLocalizedField(documentField)) {
+        return {
+            type: documentField.type,
+            items: documentField.items.map((item) =>
+                mapSourceFieldToStoreField({
+                    documentField: item,
+                    modelField: modelField.items ?? { type: 'string' },
+                    modelMap,
+                    defaultLocaleCode
+                })
+            )
+        };
+    }
+    return {
+        type: documentField.type,
+        localized: true,
+        locales: _.mapValues(documentField.locales, (locale) => {
+            return {
+                locale: locale.locale,
+                items: (locale.items ?? []).map((item) =>
+                    mapSourceFieldToStoreField({
+                        documentField: item,
+                        modelField: modelField.items ?? { type: 'string' },
+                        modelMap,
+                        defaultLocaleCode
+                    })
+                )
+            };
+        })
+    };
+}
+
+function mapRichTextField(documentField: ContentSourceTypes.DocumentRichTextField): ContentStoreTypes.DocumentRichTextField {
+    if (!isLocalizedField(documentField)) {
+        return {
+            ...documentField,
+            multiElement: true
+        };
+    }
+    return {
+        type: documentField.type,
+        localized: true,
+        locales: _.mapValues(documentField.locales, (locale) => {
+            return {
+                ...locale,
+                multiElement: true
+            };
+        })
+    };
+}
+
+function mapMarkdownField(documentField: ContentSourceTypes.DocumentValueField): ContentStoreTypes.DocumentMarkdownField {
+    if (!isLocalizedField(documentField)) {
+        return {
+            type: 'markdown',
+            value: documentField.value,
+            multiElement: true
+        };
+    }
+    return {
+        type: 'markdown',
+        localized: true,
+        locales: _.mapValues(documentField.locales, (locale) => {
+            return {
+                ...locale,
+                multiElement: true
+            };
+        })
+    };
+}
+
+function mapStoreFieldsToSourceFields({
+    documentFields,
+    modelFields,
+    modelMap
+}: {
+    documentFields: Record<string, ContentStoreTypes.DocumentField>;
+    modelFields: Field[];
+    modelMap: Record<string, Model>;
+}): Record<string, ContentSourceTypes.DocumentField> {
+    // TODO:
+    throw new Error(`duplicateDocument not implemented yet`);
+}
+
+function getContentSourceIdForContentSource(contentSource: ContentSourceTypes.ContentSourceInterface): string {
+    return getContentSourceId(contentSource.getContentSourceType(), contentSource.getProjectId());
+}
+
+function extractTokensFromString(input: string): string[] {
+    return input.match(/(?<={)[^}]+(?=})/g) || [];
+}
+
+function sanitizeSlug(slug: string) {
+    return slug
+        .split('/')
+        .map((part) => slugify(part, { lower: true }))
+        .join('/');
+}
+
+function getObjectLabel(
+    documentFields: Record<string, ContentSourceTypes.DocumentField | ContentSourceTypes.AssetFileField>,
+    modelOrObjectField: Model | FieldObjectProps,
+    locale?: string
+): string {
+    const labelField = modelOrObjectField.labelField;
+    let label = null;
+    if (labelField) {
+        const field = _.get(documentFields, labelField, null);
+        if (field && ['string', 'url', 'slug', 'text', 'markdown', 'number', 'enum', 'date', 'datetime', 'color', 'image', 'file'].includes(field.type)) {
+            if (isLocalizedField(field) && locale) {
+                label = _.get(field, ['locales', locale, 'value'], null);
+            } else if (!isLocalizedField(field)) {
+                label = _.get(field, 'value', null);
+            }
+        }
+    }
+    if (!label) {
+        label = _.get(modelOrObjectField, 'label');
+    }
+    if (!label && _.has(modelOrObjectField, 'name')) {
+        label = _.startCase(_.get(modelOrObjectField, 'name'));
+    }
+    return label;
+}
+
+function mapDocumentsToLocalizedApiObjects(documents: ContentStoreTypes.Document[], locale?: string): ContentStoreTypes.APIDocumentObject[] {
+    return documents.map((document) => documentToLocalizedApiObject(document, locale));
+}
+
+function documentToLocalizedApiObject(document: ContentStoreTypes.Document, locale?: string): ContentStoreTypes.APIDocumentObject {
+    const { type, fields, ...rest } = document;
+    return {
+        type: 'object',
+        ...rest,
+        fields: toLocalizedAPIFields(fields, locale)
+    };
+}
+
+function toLocalizedAPIFields(docFields: Record<string, ContentStoreTypes.DocumentField>, locale?: string): Record<string, ContentStoreTypes.DocumentFieldAPI> {
+    return _.mapValues(docFields, (docField) => toLocalizedAPIField(docField, locale));
+}
+
+function toLocalizedAPIField(docField: ContentStoreTypes.DocumentField, locale?: string, isListItem = false): ContentStoreTypes.DocumentFieldAPI {
+    const hasUnsetFlag = ['object', 'model', 'reference', 'richText', 'markdown', 'image', 'file', 'json'].includes(docField.type);
+    let docFieldLocalized: ContentStoreTypes.DocumentFieldNonLocalized;
+    let unset = false;
+    if (docField.localized) {
+        const { locales, localized, ...base } = docField;
+        const localeProps = locale ? locales[locale] : undefined;
+        docFieldLocalized = {
+            ...base,
+            ...localeProps,
+            ...(hasUnsetFlag && !localeProps ? { isUnset: true } : null)
+        } as ContentStoreTypes.DocumentFieldNonLocalized;
+    } else {
+        docFieldLocalized = docField;
+    }
+
+    locale = locale ?? docFieldLocalized.locale;
+    const commonProps = isListItem
+        ? null
+        : {
+              localized: !!docField.localized,
+              ...(locale ? { locale } : null)
+          };
+
+    if (docFieldLocalized.type === 'object' || docFieldLocalized.type === 'model') {
+        return {
+            ...docFieldLocalized,
+            ...commonProps,
+            ...(docFieldLocalized.isUnset
+                ? null
+                : {
+                      fields: toLocalizedAPIFields(docFieldLocalized.fields, locale)
+                  })
+        } as ContentStoreTypes.DocumentObjectFieldAPI | ContentStoreTypes.DocumentModelFieldAPI;
+    } else if (docFieldLocalized.type === 'reference') {
+        const { type, refType, ...rest } = docFieldLocalized;
+        // if reference field isUnset === true, it behaves like a regular object
+        if (rest.isUnset) {
+            return {
+                type: 'object',
+                ...rest,
+                ...commonProps
+            };
+        }
+        return {
+            type: 'unresolved_reference',
+            refType: refType === 'asset' ? 'image' : 'object',
+            ...rest,
+            ...commonProps
+        };
+    } else if (docFieldLocalized.type === 'list') {
+        const { items, ...rest } = docFieldLocalized;
+        return {
+            ...rest,
+            ...commonProps,
+            items: items.map((field) => toLocalizedAPIField(field, locale, true))
+        };
+    } else {
+        return {
+            ...docFieldLocalized,
+            ...commonProps
+        };
+    }
+}
+
+function mapAssetsToLocalizedApiImages(assets: ContentStoreTypes.Asset[], locale?: string): ContentStoreTypes.APIImageObject[] {
+    return assets.map((asset) => assetToLocalizedApiImage(asset, locale));
+}
+
+function assetToLocalizedApiImage(asset: ContentStoreTypes.Asset, locale?: string): ContentStoreTypes.APIImageObject {
+    const { type, fields, ...rest } = asset;
+    return {
+        type: 'image',
+        ...rest,
+        fields: localizeAssetFields(fields, locale)
+    };
+}
+
+function localizeAssetFields(assetFields: ContentStoreTypes.AssetFields, locale?: string): ContentStoreTypes.AssetFieldsAPI {
+    const fields: ContentStoreTypes.AssetFieldsAPI = {
+        title: {
+            type: 'string' as const,
+            value: null as any
+        },
+        url: {
+            type: 'string' as const,
+            value: null as any
+        }
+    };
+    const titleFieldNonLocalized = getDocumentFieldForLocale(assetFields.title, locale);
+    fields.title.value = titleFieldNonLocalized?.value;
+    fields.title.locale = locale ?? titleFieldNonLocalized?.locale;
+    const assetFileField = assetFields.file;
+    if (assetFileField.localized) {
+        if (locale) {
+            fields.url.value = assetFileField.locales[locale]?.url ?? null;
+            fields.url.locale = locale;
+        }
+    } else {
+        fields.url.value = assetFileField.url;
+        fields.url.locale = assetFileField.locale;
+    }
+    return fields;
+}
+
+function mapStoreAssetsToAPIAssets(assets: ContentStoreTypes.Asset[], locale?: string): ContentStoreTypes.APIAsset[] {
+    return assets.map((asset) => storeAssetToAPIAsset(asset, locale));
+}
+
+function storeAssetToAPIAsset(asset: ContentStoreTypes.Asset, locale?: string): ContentStoreTypes.APIAsset {
+    const assetTitleField = asset.fields.title;
+    const localizedTitleField = assetTitleField.localized ? assetTitleField.locales[locale!]! : assetTitleField;
+    const assetFileField = asset.fields.file;
+    const localizedFileField = assetFileField.localized ? assetFileField.locales[locale!]! : assetFileField;
+    return {
+        objectId: asset.srcObjectId,
+        createdAt: asset.createdAt,
+        url: localizedFileField.url,
+        ...omitByNil({
+            title: localizedTitleField.value,
+            fileName: localizedFileField.fileName,
+            contentType: localizedFileField.contentType,
+            size: localizedFileField.size,
+            width: localizedFileField.dimensions?.width,
+            height: localizedFileField.dimensions?.height
+        })
+    };
+}
+
+/**
+ * Iterates recursively objects with $$type and $$ref, creating nested objects
+ * as needed and returns standard ContentSourceInterface Documents
+ */
+async function createDocumentRecursively({
+    object,
+    model,
+    modelMap,
+    locale,
+    userContext,
+    contentSourceInstance
+}: {
+    object?: Record<string, any>;
+    model: Model;
+    modelMap: Record<string, Model>;
+    locale?: string;
+    userContext: unknown;
+    contentSourceInstance: ContentSourceTypes.ContentSourceInterface;
+}): Promise<{ document: ContentSourceTypes.Document; newRefDocuments: ContentSourceTypes.Document[] }> {
+    if (model.type === 'page') {
+        const tokens = extractTokensFromString(String(model.urlPath));
+        const slugField = _.last(tokens);
+        if (object && slugField && slugField in object) {
+            const slugFieldValue = object[slugField];
+            object[slugField] = sanitizeSlug(slugFieldValue);
+        }
+    }
+
+    const nestedResult = await createNestedObjectRecursively({
+        object,
+        modelFields: model.fields ?? [],
+        fieldPath: [],
+        modelMap,
+        locale,
+        userContext,
+        contentSourceInstance
+    });
+    const document = await contentSourceInstance.createDocument({
+        documentFields: nestedResult.fields,
+        model,
+        modelMap,
+        locale,
+        userContext
+    });
+    return {
+        document: document,
+        newRefDocuments: nestedResult.newRefDocuments
+    };
+}
+
+async function createNestedObjectRecursively({
+    object,
+    modelFields,
+    fieldPath,
+    modelMap,
+    locale,
+    userContext,
+    contentSourceInstance
+}: {
+    object?: Record<string, any>;
+    modelFields: Field[];
+    fieldPath: (string | number)[];
+    modelMap: Record<string, Model>;
+    locale?: string;
+    userContext: unknown;
+    contentSourceInstance: ContentSourceTypes.ContentSourceInterface;
+}): Promise<{
+    fields: Record<string, ContentSourceTypes.DocumentFieldNonLocalized>;
+    newRefDocuments: ContentSourceTypes.Document[];
+}> {
+    const createNestedField = async ({
+        value,
+        modelField,
+        fieldPath
+    }: {
+        value: any;
+        modelField: FieldSpecificProps;
+        fieldPath: (string | number)[];
+    }): Promise<{ field: ContentSourceTypes.DocumentFieldNonLocalized; newRefDocuments: ContentSourceTypes.Document[] }> => {
+        if (modelField.type === 'object') {
+            const result = await createNestedObjectRecursively({
+                object: value,
+                modelFields: modelField.fields,
+                fieldPath,
+                modelMap,
+                locale,
+                userContext,
+                contentSourceInstance
+            });
+            return {
+                field: {
+                    type: 'object',
+                    fields: result.fields
+                },
+                newRefDocuments: result.newRefDocuments
+            };
+        } else if (modelField.type === 'model') {
+            let { $$type, ...rest } = value;
+            const modelNames = modelField.models;
+            // for backward compatibility check if the object has 'type' instead of '$$type' because older projects use
+            // the 'type' property in default values
+            if (!$$type && 'type' in rest) {
+                $$type = rest.type;
+                rest = _.omit(rest, 'type');
+            }
+            const modelName = $$type ?? (modelNames.length === 1 ? modelNames[0] : null);
+            if (!modelName) {
+                throw new Error(`no $$type was specified for nested model`);
+            }
+            const model = modelMap[modelName];
+            if (!model) {
+                throw new Error(`no model with name '${modelName}' was found`);
+            }
+            const result = await createNestedObjectRecursively({
+                object: rest,
+                modelFields: model.fields ?? [],
+                fieldPath,
+                modelMap,
+                locale,
+                userContext,
+                contentSourceInstance
+            });
+            return {
+                field: {
+                    type: 'model',
+                    modelName: modelName,
+                    fields: result.fields
+                },
+                newRefDocuments: result.newRefDocuments
+            };
+        } else if (modelField.type === 'image') {
+            let refId: string | undefined;
+            if (_.isPlainObject(value)) {
+                refId = value.$$ref;
+            } else {
+                refId = value;
+            }
+            if (!refId) {
+                throw new Error(`reference field must specify a value`);
+            }
+            return {
+                field: {
+                    type: 'reference',
+                    refType: 'asset',
+                    refId: refId
+                },
+                newRefDocuments: []
+            };
+        } else if (modelField.type === 'reference') {
+            let { $$ref: refId = null, $$type: modelName = null, ...rest } = _.isPlainObject(value) ? value : { $$ref: value };
+            if (refId) {
+                return {
+                    field: {
+                        type: 'reference',
+                        refType: 'document',
+                        refId: refId
+                    },
+                    newRefDocuments: []
+                };
+            } else {
+                const modelNames = modelField.models;
+                if (!modelName) {
+                    // for backward compatibility check if the object has 'type' instead of '$$type' because older projects use
+                    // the 'type' property in default values
+                    if ('type' in rest) {
+                        modelName = rest.type;
+                        rest = _.omit(rest, 'type');
+                    } else if (modelNames.length === 1) {
+                        modelName = modelNames[0];
+                    }
+                }
+                const model = modelMap[modelName];
+                if (!model) {
+                    throw new Error(`no model with name '${modelName}' was found`);
+                }
+                const { document, newRefDocuments } = await createDocumentRecursively({
+                    object: rest,
+                    model: model,
+                    modelMap,
+                    locale,
+                    userContext,
+                    contentSourceInstance
+                });
+                return {
+                    field: {
+                        type: 'reference',
+                        refType: 'document',
+                        refId: document.id
+                    },
+                    newRefDocuments: [document, ...newRefDocuments]
+                };
+            }
+        } else if (modelField.type === 'list') {
+            if (!Array.isArray(value)) {
+                throw new Error(`value for list field must be array`);
+            }
+            const itemsField = modelField.items;
+            if (!itemsField) {
+                throw new Error(`list field does not define items`);
+            }
+            const arrayResult = await mapPromise(value, async (item, index) => {
+                return createNestedField({
+                    value: item,
+                    modelField: itemsField,
+                    fieldPath: fieldPath.concat(index)
+                });
+            });
+            return {
+                field: {
+                    type: 'list',
+                    items: arrayResult.map((result) => result.field)
+                },
+                newRefDocuments: arrayResult.reduce((result: ContentSourceTypes.Document[], { newRefDocuments }) => result.concat(newRefDocuments), [])
+            };
+        }
+        return {
+            field: {
+                type: modelField.type,
+                value: value
+            } as ContentSourceTypes.DocumentFieldNonLocalized,
+            newRefDocuments: []
+        };
+    };
+
+    object = object ?? {};
+    const result: {
+        fields: Record<string, ContentSourceTypes.DocumentFieldNonLocalized>;
+        newRefDocuments: ContentSourceTypes.Document[];
+    } = {
+        fields: {},
+        newRefDocuments: []
+    };
+    const objectFieldNames = Object.keys(object);
+    for (const modelField of modelFields) {
+        const fieldName = modelField.name;
+        let value;
+        if (fieldName in object) {
+            value = object[fieldName];
+            _.pull(objectFieldNames, fieldName);
+        } else if (modelField.const) {
+            value = modelField.const;
+        } else if (!_.isNil(modelField.default)) {
+            value = modelField.default;
+        }
+        if (!_.isNil(value)) {
+            const fieldResult = await createNestedField({
+                value,
+                modelField,
+                fieldPath: fieldPath.concat(fieldName)
+            });
+            result.fields[fieldName] = fieldResult.field;
+            result.newRefDocuments = result.newRefDocuments.concat(fieldResult.newRefDocuments);
+        }
+    }
+    if (objectFieldNames.length > 0) {
+        throw new Error(`no model fields found when creating a document with fields: '${objectFieldNames.join(', ')}'`);
+    }
+
+    return result;
+}
+
+function getModelFieldForFieldAtPath(
+    document: ContentStoreTypes.Document,
+    model: Model,
+    fieldPath: (string | number)[],
+    modelMap: Record<string, Model>,
+    locale?: string
+): Field {
+    if (_.isEmpty(fieldPath)) {
+        throw new Error('the fieldPath can not be empty');
+    }
+
+    function getField(docField: ContentStoreTypes.DocumentField, modelField: FieldSpecificProps, fieldPath: (string | number)[]): Field {
+        const fieldName = _.head(fieldPath);
+        if (typeof fieldName === 'undefined') {
+            throw new Error('the first fieldPath item must be string');
+        }
+        const childFieldPath = _.tail(fieldPath);
+        let childDocField: ContentStoreTypes.DocumentField | undefined;
+        let childModelField: Field | undefined;
+        switch (docField.type) {
+            case 'object':
+                const localizedObjectField = getDocumentFieldForLocale(docField, locale);
+                if (!localizedObjectField) {
+                    throw new Error(`locale for field was not found`);
+                }
+                if (localizedObjectField.isUnset) {
+                    throw new Error(`field is not set`);
+                }
+                childDocField = localizedObjectField.fields[fieldName];
+                childModelField = _.find((modelField as FieldObjectProps).fields, (field) => field.name === fieldName);
+                if (!childDocField || !childModelField) {
+                    throw new Error(`field ${fieldName} doesn't exist`);
+                }
+                if (childFieldPath.length === 0) {
+                    return childModelField;
+                }
+                return getField(childDocField, childModelField, childFieldPath);
+            case 'model':
+                const localizedModelField = getDocumentFieldForLocale(docField, locale);
+                if (!localizedModelField) {
+                    throw new Error(`locale for field was not found`);
+                }
+                if (localizedModelField.isUnset) {
+                    throw new Error(`field is not set`);
+                }
+                const modelName = localizedModelField.srcModelName;
+                const childModel = modelMap[modelName];
+                if (!childModel) {
+                    throw new Error(`model ${modelName} doesn't exist`);
+                }
+                childModelField = _.find(childModel.fields, (field) => field.name === fieldName);
+                childDocField = localizedModelField.fields![fieldName];
+                if (!childDocField || !childModelField) {
+                    throw new Error(`field ${fieldName} doesn't exist`);
+                }
+                if (childFieldPath.length === 0) {
+                    return childModelField;
+                }
+                return getField(childDocField, childModelField!, childFieldPath);
+            case 'list':
+                const localizedListField = getDocumentFieldForLocale(docField, locale);
+                if (!localizedListField) {
+                    throw new Error(`locale for field was not found`);
+                }
+                const listItem = localizedListField.items && localizedListField.items[fieldName as number];
+                const listItemsModel = (modelField as FieldListProps).items;
+                if (!listItem || !listItemsModel) {
+                    throw new Error(`field ${fieldName} doesn't exist`);
+                }
+                if (childFieldPath.length === 0) {
+                    return modelField as FieldList;
+                }
+                if (!Array.isArray(listItemsModel)) {
+                    return getField(listItem, listItemsModel, childFieldPath);
+                } else {
+                    const fieldListItems = (listItemsModel as FieldListItems[]).find((listItemsModel) => listItemsModel.type === listItem.type);
+                    if (!fieldListItems) {
+                        throw new Error('cannot find matching field model');
+                    }
+                    return getField(listItem, fieldListItems, childFieldPath);
+                }
+            default:
+                if (!_.isEmpty(childFieldPath)) {
+                    throw new Error('illegal fieldPath');
+                }
+                return modelField as Field;
+        }
+    }
+
+    const fieldName = _.head(fieldPath);
+    const childFieldPath = _.tail(fieldPath);
+
+    if (typeof fieldName !== 'string') {
+        throw new Error('the first fieldPath item must be string');
+    }
+
+    const childDocField = document.fields[fieldName];
+    const childModelField = _.find(model.fields, { name: fieldName });
+
+    if (!childDocField || !childModelField) {
+        throw new Error(`field ${fieldName} doesn't exist`);
+    }
+
+    if (childFieldPath.length === 0) {
+        return childModelField;
+    }
+
+    return getField(childDocField, childModelField, childFieldPath);
+}
+
+async function convertOperationField({
+    operationField,
+    fieldPath,
+    modelField,
+    modelMap,
+    locale,
+    userContext,
+    contentSourceInstance
+}: {
+    operationField: ContentStoreTypes.UpdateOperationField;
+    fieldPath: (string | number)[];
+    modelField: Field;
+    modelMap: Record<string, Model>;
+    locale?: string;
+    userContext: unknown;
+    contentSourceInstance: ContentSourceTypes.ContentSourceInterface;
+}): Promise<ContentSourceTypes.UpdateOperationField> {
+    let result;
+    switch (operationField.type) {
+        case 'object':
+            result = await createNestedObjectRecursively({
+                object: operationField.object,
+                modelFields: (modelField as FieldObjectProps).fields,
+                fieldPath: fieldPath,
+                modelMap,
+                locale,
+                userContext,
+                contentSourceInstance
+            });
+            return {
+                type: operationField.type,
+                fields: result.fields
+            };
+        case 'model':
+            const model = modelMap[operationField.modelName];
+            if (!model) {
+                throw new Error(`error updating document, could not find document model: '${operationField.modelName}'`);
+            }
+            result = await createNestedObjectRecursively({
+                object: operationField.object,
+                modelFields: model.fields!,
+                fieldPath,
+                modelMap,
+                locale,
+                userContext,
+                contentSourceInstance
+            });
+            return {
+                type: operationField.type,
+                modelName: operationField.modelName,
+                fields: result.fields
+            };
+        default:
+            return operationField as ContentSourceTypes.UpdateOperationField;
+    }
+}
+
+function getDocumentFieldForLocale<Type extends ContentStoreTypes.FieldType>(
+    docField: ContentStoreTypes.DocumentFieldForType<Type>,
+    locale?: string
+): ContentStoreTypes.DocumentFieldNonLocalizedForType<Type> | null {
+    if (docField.localized) {
+        if (!locale) {
+            return null;
+        }
+        const { localized, locales, ...base } = docField;
+        const localizedField = locales[locale];
+        if (!localizedField) {
+            return null;
+        }
+        return ({
+            ...base,
+            ...localizedField
+        } as unknown) as ContentStoreTypes.DocumentFieldNonLocalizedForType<Type>;
+    } else {
+        return docField;
+    }
+}
+
+function isStackbitConfigFile(filePath: string) {
+    const pathObject = path.parse(filePath);
+    const isInDotStackbitFolder = pathObject.dir.startsWith('.stackbit');
+    const isMainStackbitConfigFile = pathObject.name === 'stackbit' && ['yaml', 'yml'].includes(pathObject.ext.substring(1));
+    return isMainStackbitConfigFile || isInDotStackbitFolder;
+}