@kontent-ai/migration-toolkit 2.9.1 → 3.0.0-1

package/lib/export/export.models.ts

@@ -1,90 +1,105 @@
 import type {
-    AssetFolderModels,
-    CollectionModels,
-    ContentItemModels,
-    LanguageModels,
-    LanguageVariantModels,
-    ManagementClient,
-    SharedModels,
-    TaxonomyModels,
-    WorkflowModels
-} from '@kontent-ai/management-sdk';
+	AssetFolderModels,
+	CollectionModels,
+	ContentItemModels,
+	LanguageModels,
+	LanguageVariantModels,
+	ManagementClient,
+	SharedModels,
+	TaxonomyModels,
+	WorkflowModels,
+} from "@kontent-ai/management-sdk";
 import type {
-    AssetStateInSourceEnvironmentById,
-    FlattenedContentType,
-    FlattenedContentTypeElement,
-    ItemStateInSourceEnvironmentById,
-    Logger,
-    ManagementClientConfig,
-    MigrationComponent,
-    MigrationElementTransformData,
-    MigrationUrlSlugMode,
-    ReferencedDataInLanguageVariants
-} from '../core/index.js';
+	AssetStateInSourceEnvironmentById,
+	FlattenedContentType,
+	FlattenedContentTypeElement,
+	ItemStateInSourceEnvironmentById,
+	ReferencedDataInLanguageVariants,
+} from "../core/models/core.models.js";
+import type { Logger } from "../core/models/log.models.js";
+import type { MigrationComponent, MigrationElementTransformData, MigrationUrlSlugMode } from "../core/models/migration.models.js";
+import type { ManagementClientConfig } from "../core/utils/management-client-utils.js";
 
 export interface ExportContextEnvironmentData {
-    readonly languages: readonly Readonly<LanguageModels.LanguageModel>[];
-    readonly contentTypes: readonly Readonly<FlattenedContentType>[];
-    readonly collections: readonly Readonly<CollectionModels.Collection>[];
-    readonly assetFolders: readonly Readonly<AssetFolderModels.AssetFolder>[];
-    readonly workflows: readonly Readonly<WorkflowModels.Workflow>[];
-    readonly taxonomies: readonly Readonly<TaxonomyModels.Taxonomy>[];
+	readonly languages: readonly Readonly<LanguageModels.LanguageModel>[];
+	readonly contentTypes: readonly Readonly<FlattenedContentType>[];
+	readonly collections: readonly Readonly<CollectionModels.Collection>[];
+	readonly assetFolders: readonly Readonly<AssetFolderModels.AssetFolder>[];
+	readonly workflows: readonly Readonly<WorkflowModels.Workflow>[];
+	readonly taxonomies: readonly Readonly<TaxonomyModels.Taxonomy>[];
 }
 
 export type ExportElementValue = string | number | SharedModels.ReferenceObject[] | undefined;
 
 export interface ExportElement {
-    readonly value: ExportElementValue;
-    readonly components: readonly MigrationComponent[];
-    readonly urlSlugMode: MigrationUrlSlugMode | undefined;
-    readonly displayTimezone: string | undefined;
+	readonly value: ExportElementValue;
+	readonly components: readonly MigrationComponent[];
+	readonly urlSlugMode: MigrationUrlSlugMode | undefined;
+	readonly displayTimezone: string | undefined;
 }
 
 export type ExportTransformFunc = (data: {
-    readonly typeElement: FlattenedContentTypeElement;
-    readonly exportElement: ExportElement;
-    readonly context: ExportContext;
+	readonly typeElement: FlattenedContentTypeElement;
+	readonly exportElement: ExportElement;
+	readonly context: ExportContext;
 }) => MigrationElementTransformData;
 
 export interface ExportContext {
-    readonly environmentData: ExportContextEnvironmentData;
-    readonly referencedData: ReferencedDataInLanguageVariants;
-    readonly getItemStateInSourceEnvironment: (id: string) => ItemStateInSourceEnvironmentById;
-    readonly getAssetStateInSourceEnvironment: (id: string) => AssetStateInSourceEnvironmentById;
-    readonly exportItems: readonly ExportItem[];
-    readonly getElement: GetFlattenedElementByIds;
+	readonly environmentData: ExportContextEnvironmentData;
+	readonly referencedData: ReferencedDataInLanguageVariants;
+	readonly getItemStateInSourceEnvironment: (id: string) => ItemStateInSourceEnvironmentById;
+	readonly getAssetStateInSourceEnvironment: (id: string) => AssetStateInSourceEnvironmentById;
+	readonly exportItems: readonly ExportItem[];
+	readonly getElement: GetFlattenedElementByIds;
+	readonly exportContextOptions: ExportContextOptions;
 }
 
 export interface SourceExportItem {
-    readonly itemCodename: string;
-    readonly languageCodename: string;
+	readonly itemCodename: string;
+	readonly languageCodename: string;
+}
+
+export interface ExportContextOptions {
+	/**
+	 * When enabled, the export process will skip missing items and assets instead of throwing errors.
+	 * Missing references will be filtered out from the exported data.
+	 * Default: false
+	 */
+	readonly skipMissingReferences?: boolean;
 }
 
 export interface ExportConfig extends ManagementClientConfig {
-    readonly exportItems: readonly SourceExportItem[];
-    readonly logger?: Logger;
+	readonly exportItems: readonly SourceExportItem[];
+	readonly logger?: Logger;
+	/**
+	 * When enabled, the export process will skip missing items and assets instead of throwing errors.
+	 * Missing references will be filtered out from the exported data.
+	 * Default: false
+	 */
+	readonly skipMissingReferences?: boolean;
 }
 
 export interface DefaultExportContextConfig {
-    readonly logger: Logger;
-    readonly exportItems: readonly SourceExportItem[];
-    readonly managementClient: Readonly<ManagementClient>;
+	readonly logger: Logger;
+	readonly exportItems: readonly SourceExportItem[];
+	readonly managementClient: Readonly<ManagementClient>;
+	readonly skipMissingReferences: boolean;
 }
 
 export type GetFlattenedElementByIds = (contentTypeId: string, elementId: string) => FlattenedContentTypeElement;
 
 export interface ExportItemVersion {
-    readonly workflowStepCodename: string;
-    readonly languageVariant: Readonly<LanguageVariantModels.ContentItemLanguageVariant>;
+	readonly workflowStepCodename: string;
+	readonly languageVariant: Readonly<LanguageVariantModels.ContentItemLanguageVariant>;
 }
 
 export interface ExportItem {
-    readonly requestItem: SourceExportItem;
-    readonly versions: readonly ExportItemVersion[];
-    readonly contentItem: Readonly<ContentItemModels.ContentItem>;
+	readonly requestItem: SourceExportItem;
+	readonly versions: readonly ExportItemVersion[];
+	readonly contentItem: Readonly<ContentItemModels.ContentItem>;
 
-    readonly collection: Readonly<CollectionModels.Collection>;
-    readonly language: Readonly<LanguageModels.LanguageModel>;
-    readonly workflow: Readonly<WorkflowModels.Workflow>;
-    readonly contentType: Readonly<FlattenedContentType>;
+	readonly collection: Readonly<CollectionModels.Collection>;
+	readonly language: Readonly<LanguageModels.LanguageModel>;
+	readonly workflow: Readonly<WorkflowModels.Workflow>;
+	readonly contentType: Readonly<FlattenedContentType>;
 }

package/lib/export/utils/export.utils.ts

@@ -1,10 +1,12 @@
-import chalk from 'chalk';
-import type { SourceExportItem } from '../export.models.js';
+import chalk from "chalk";
+import { MigrationToolkitError } from "../../core/models/error.models.js";
+import type { SourceExportItem } from "../export.models.js";
 
 export function throwErrorForItemRequest(itemRequest: SourceExportItem, message: string): never {
-    throw Error(
-        `Export failed for item '${chalk.yellow(itemRequest.itemCodename)}' in language '${chalk.cyan(
-            itemRequest.languageCodename
-        )}'. Reason: ${message}`
-    );
+	throw new MigrationToolkitError(
+		"exportFailedForItem",
+		`Export failed for item '${chalk.yellow(itemRequest.itemCodename)}' in language '${chalk.cyan(
+			itemRequest.languageCodename,
+		)}'. Reason: ${message}`,
+	);
 }

package/lib/file/file-manager.ts

@@ -1,38 +1,38 @@
-import type { Buffer as BufferProxy } from 'buffer';
-import chalk from 'chalk';
-import { promises } from 'fs';
-import type { Logger } from '../core/index.js';
+import { promises } from "node:fs";
+import type { Buffer as BufferProxy } from "buffer";
+import chalk from "chalk";
+import type { Logger } from "../core/models/log.models.js";
 
 export function fileManager(logger: Logger) {
-    const getFilePath = (filename: string): string => {
-        return `./${filename}`;
-    };
+	const getFilePath = (filename: string): string => {
+		return `./${filename}`;
+	};
 
-    const loadFileAsync = async (filename: string): Promise<BufferProxy> => {
-        const filePath = getFilePath(filename);
+	const loadFileAsync = async (filename: string): Promise<BufferProxy> => {
+		const filePath = getFilePath(filename);
 
-        logger.log({
-            type: 'readFs',
-            message: `Reading file '${chalk.yellow(filePath)}'`
-        });
+		logger.log({
+			type: "readFs",
+			message: `Reading file '${chalk.yellow(filePath)}'`,
+		});
 
-        const file = await promises.readFile(filePath);
+		const file = await promises.readFile(filePath);
 
-        return file;
-    };
+		return file;
+	};
 
-    const writeFileAsync = async (fileNameWithoutExtension: string, content: string | BufferProxy): Promise<void> => {
-        const filePath = getFilePath(fileNameWithoutExtension);
+	const writeFileAsync = async (fileNameWithoutExtension: string, content: string | BufferProxy): Promise<void> => {
+		const filePath = getFilePath(fileNameWithoutExtension);
 
-        logger.log({
-            type: 'writeFs',
-            message: `Storing file '${chalk.yellow(filePath)}'`
-        });
-        await promises.writeFile(filePath, content);
-    };
+		logger.log({
+			type: "writeFs",
+			message: `Storing file '${chalk.yellow(filePath)}'`,
+		});
+		await promises.writeFile(filePath, content);
+	};
 
-    return {
-        loadFileAsync,
-        writeFileAsync
-    };
+	return {
+		loadFileAsync,
+		writeFileAsync,
+	};
 }

package/lib/import/comparers/asset-comparer.ts

@@ -1,106 +1,107 @@
-import type { AssetFolderModels, AssetModels, CollectionModels, LanguageModels } from '@kontent-ai/management-sdk';
-import deepEqual from 'deep-equal';
-import type { MigrationAsset, MigrationAssetDescription } from '../../core/index.js';
-import { findRequired, geSizeInBytes } from '../../core/index.js';
-
-export function shouldUpdateAsset(data: {
-    readonly migrationAsset: MigrationAsset;
-    readonly targetAsset: Readonly<AssetModels.Asset>;
-    readonly collections: readonly Readonly<CollectionModels.Collection>[];
-    readonly languages: readonly Readonly<LanguageModels.LanguageModel>[];
-    readonly assetFolders: readonly Readonly<AssetFolderModels.AssetFolder>[];
-}): boolean {
-    return (
-        !isInSameCollection(data) ||
-        !areDescriptionsIdentical(data) ||
-        !isTitleIdentical(data) ||
-        !isFolderIdentical(data) ||
-        !isBinaryFileIdentical(data)
-    );
-}
-
-export function shouldReplaceBinaryFile(data: {
-    readonly migrationAsset: MigrationAsset;
-    readonly targetAsset: Readonly<AssetModels.Asset>;
-}): boolean {
-    return !isBinaryFileIdentical(data);
-}
-
-function isBinaryFileIdentical(data: {
-    readonly migrationAsset: MigrationAsset;
-    readonly targetAsset: Readonly<AssetModels.Asset>;
-}): boolean {
-    const sourceFileSize = geSizeInBytes(data.migrationAsset.binary_data);
-    const targetFileSize = data.targetAsset.size;
-
-    const sourceFilename = data.migrationAsset.filename;
-    const targetFilename = data.targetAsset.fileName;
-
-    return sourceFileSize === targetFileSize && sourceFilename === targetFilename;
-}
-
-function isFolderIdentical(data: {
-    readonly migrationAsset: MigrationAsset;
-    readonly targetAsset: Readonly<AssetModels.Asset>;
-    readonly assetFolders: readonly Readonly<AssetFolderModels.AssetFolder>[];
-}): boolean {
-    return data.assetFolders.find((m) => m.id === data.targetAsset.folder?.id)?.codename === data.migrationAsset.folder?.codename;
-}
-
-function isTitleIdentical(data: { readonly migrationAsset: MigrationAsset; readonly targetAsset: Readonly<AssetModels.Asset> }): boolean {
-    const sourceTitle = data.migrationAsset.title?.length ? data.migrationAsset.title : undefined;
-    const targetTitle = data.targetAsset.title?.length ? data.targetAsset.title : undefined;
-
-    return sourceTitle === targetTitle;
-}
-
-function isInSameCollection(data: {
-    readonly migrationAsset: MigrationAsset;
-    readonly targetAsset: Readonly<AssetModels.Asset>;
-    readonly collections: readonly Readonly<CollectionModels.Collection>[];
-}): boolean {
-    return (
-        data.collections.find((m) => m.id === data.targetAsset.collection?.reference?.id)?.codename ===
-        data.migrationAsset.collection?.codename
-    );
-}
-
-function areDescriptionsIdentical(data: {
-    readonly migrationAsset: MigrationAsset;
-    readonly targetAsset: Readonly<AssetModels.Asset>;
-    readonly languages: readonly Readonly<LanguageModels.LanguageModel>[];
-}): boolean {
-    const sourceMigrationDescriptions = (data.migrationAsset.descriptions ?? [])
-        .map<MigrationAssetDescription>((description) => {
-            return {
-                description: description.description?.length ? description.description : undefined,
-                language: {
-                    codename: description.language.codename
-                }
-            };
-        })
-        .toSorted();
-    const targetMigrationDescriptions = mapToMigrationDescriptions(data).toSorted();
-
-    return deepEqual(sourceMigrationDescriptions, targetMigrationDescriptions);
-}
-
-function mapToMigrationDescriptions(data: {
-    readonly targetAsset: Readonly<AssetModels.Asset>;
-    readonly languages: readonly Readonly<LanguageModels.LanguageModel>[];
-}): MigrationAssetDescription[] {
-    return data.targetAsset.descriptions.map((description) => {
-        const languageId = description.language.id;
-
-        return {
-            description: description.description?.length ? description.description : undefined,
-            language: {
-                codename: findRequired(
-                    data.languages,
-                    (language) => language.id === languageId,
-                    `Could not find language with id '${languageId}'`
-                ).codename
-            }
-        };
-    });
-}
+import type { AssetFolderModels, AssetModels, CollectionModels, LanguageModels } from "@kontent-ai/management-sdk";
+import deepEqual from "deep-equal";
+import type { MigrationAsset, MigrationAssetDescription } from "../../core/models/migration.models.js";
+import { findRequired } from "../../core/utils/array.utils.js";
+import { geSizeInBytes } from "../../core/utils/binary-data.utils.js";
+
+export function shouldUpdateAsset(data: {
+	readonly migrationAsset: MigrationAsset;
+	readonly targetAsset: Readonly<AssetModels.Asset>;
+	readonly collections: readonly Readonly<CollectionModels.Collection>[];
+	readonly languages: readonly Readonly<LanguageModels.LanguageModel>[];
+	readonly assetFolders: readonly Readonly<AssetFolderModels.AssetFolder>[];
+}): boolean {
+	return !(
+		isInSameCollection(data) &&
+		areDescriptionsIdentical(data) &&
+		isTitleIdentical(data) &&
+		isFolderIdentical(data) &&
+		isBinaryFileIdentical(data)
+	);
+}
+
+export function shouldReplaceBinaryFile(data: {
+	readonly migrationAsset: MigrationAsset;
+	readonly targetAsset: Readonly<AssetModels.Asset>;
+}): boolean {
+	return !isBinaryFileIdentical(data);
+}
+
+function isBinaryFileIdentical(data: {
+	readonly migrationAsset: MigrationAsset;
+	readonly targetAsset: Readonly<AssetModels.Asset>;
+}): boolean {
+	const sourceFileSize = geSizeInBytes(data.migrationAsset.binary_data);
+	const targetFileSize = data.targetAsset.size;
+
+	const sourceFilename = data.migrationAsset.filename;
+	const targetFilename = data.targetAsset.fileName;
+
+	return sourceFileSize === targetFileSize && sourceFilename === targetFilename;
+}
+
+function isFolderIdentical(data: {
+	readonly migrationAsset: MigrationAsset;
+	readonly targetAsset: Readonly<AssetModels.Asset>;
+	readonly assetFolders: readonly Readonly<AssetFolderModels.AssetFolder>[];
+}): boolean {
+	return data.assetFolders.find((m) => m.id === data.targetAsset.folder?.id)?.codename === data.migrationAsset.folder?.codename;
+}
+
+function isTitleIdentical(data: { readonly migrationAsset: MigrationAsset; readonly targetAsset: Readonly<AssetModels.Asset> }): boolean {
+	const sourceTitle = data.migrationAsset.title?.length ? data.migrationAsset.title : undefined;
+	const targetTitle = data.targetAsset.title?.length ? data.targetAsset.title : undefined;
+
+	return sourceTitle === targetTitle;
+}
+
+function isInSameCollection(data: {
+	readonly migrationAsset: MigrationAsset;
+	readonly targetAsset: Readonly<AssetModels.Asset>;
+	readonly collections: readonly Readonly<CollectionModels.Collection>[];
+}): boolean {
+	return (
+		data.collections.find((m) => m.id === data.targetAsset.collection?.reference?.id)?.codename ===
+		data.migrationAsset.collection?.codename
+	);
+}
+
+function areDescriptionsIdentical(data: {
+	readonly migrationAsset: MigrationAsset;
+	readonly targetAsset: Readonly<AssetModels.Asset>;
+	readonly languages: readonly Readonly<LanguageModels.LanguageModel>[];
+}): boolean {
+	const sourceMigrationDescriptions = (data.migrationAsset.descriptions ?? [])
+		.map<MigrationAssetDescription>((description) => {
+			return {
+				description: description.description?.length ? description.description : undefined,
+				language: {
+					codename: description.language.codename,
+				},
+			};
+		})
+		.toSorted();
+	const targetMigrationDescriptions = mapToMigrationDescriptions(data).toSorted();
+
+	return deepEqual(sourceMigrationDescriptions, targetMigrationDescriptions);
+}
+
+function mapToMigrationDescriptions(data: {
+	readonly targetAsset: Readonly<AssetModels.Asset>;
+	readonly languages: readonly Readonly<LanguageModels.LanguageModel>[];
+}): MigrationAssetDescription[] {
+	return data.targetAsset.descriptions.map((description) => {
+		const languageId = description.language.id;
+
+		return {
+			description: description.description?.length ? description.description : undefined,
+			language: {
+				codename: findRequired(
+					data.languages,
+					(language) => language.id === languageId,
+					`Could not find language with id '${languageId}'`,
+				).codename,
+			},
+		};
+	});
+}