New export option: Tolerate Missing References

[zstarkebaum-bluemodus]

Motivation

⚠️ Note: This is a supporting PR for kontent-ai/data-ops#162

Adds support for tolerateMissingReferences parameter to allow exports and migrations to continue when referenced items or assets are missing, instead of throwing errors and halting the process.

This is useful in scenarios where:

• Content references items/assets that have been deleted

The parameter defaults to false to maintain backward compatibility and existing error-throwing behavior.

Checklist

• Code follows coding conventions held in this repo
• Automated tests have been added
• Tests are passing
• Docs have been updated (if applicable)
• Temporary settings (e.g. variables used during development and testing) have been reverted to defaults

How to test

Manual CLI Testing:

1. Build the project: npm run build

2. Test export with the new parameter:

node dist/node/cli/app.js export \
  --environmentId=<your-env-id> \
  --apiKey=<your-api-key> \
  --tolerateMissingReferences

3. Test migrate with the new parameter:

node dist/node/cli/app.js migrate \
  --sourceEnvironmentId=<source-env-id> \
  --sourceApiKey=<source-api-key> \
  --targetEnvironmentId=<target-env-id> \
  --targetApiKey=<target-api-key> \
  --tolerateMissingReferences

4. Verify help text shows new parameter:

node dist/node/cli/app.js export --help
node dist/node/cli/app.js migrate --help

Programmatic API Testing:

import { exportAsync, migrateAsync } from '@kontent-ai/migration-toolkit';

// Export with tolerateMissingReferences
await exportAsync({
  environmentId: 'your-env-id',
  apiKey: 'your-api-key',
  exportItems: [
    { itemCodename: 'item1', languageCodename: 'default' },
    { itemCodename: 'item2', languageCodename: 'default' }
  ],
  tolerateMissingReferences: true
});

// Migrate with tolerateMissingReferences
await migrateAsync({
  sourceEnvironment: {
    environmentId: 'source-env-id',
    apiKey: 'source-api-key',
    items: [
      { itemCodename: 'item1', languageCodename: 'default' },
      { itemCodename: 'item2', languageCodename: 'default' }
    ],
    tolerateMissingReferences: true
  },
  targetEnvironment: {
    environmentId: 'target-env-id',
    apiKey: 'target-api-key'
  }
});

[Enngage]

Hey @zstarkebaum-bluemodus,

Thanks for the PR! The idea behind this makes sense, so I'll look into this and test it a bit more. I'll likely push a few minor changes, but you can expect this feature to be included within next release ;)

[zstarkebaum-bluemodus]

Any changes are very welcome. Let me know if you have any questions. The main issue this is solving is for us specifically is trying to copy items from a Prod env to a Dev env, but the Prod env often has deleted items and the references to the deleted items were never cleaned up.

[Copilot]

Pull request overview

This PR adds support for a skipMissingReferences parameter that allows exports and migrations to continue when referenced items or assets are missing, instead of throwing errors and halting the process. The parameter defaults to false to maintain backward compatibility.

Key changes:

• Introduces new error classes (MissingItemError, MissingAssetError) with structured error types
• Updates export transforms to handle missing references by either throwing errors or filtering them out
• Adds discriminated union types for asset/item states with exists, doesNotExists, and skip states
• Implements placeholder utility for missing references in rich text content

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/export-transforms.test.ts	Comprehensive test coverage for all export transform element types with missing reference scenarios
lib/export/export.models.ts	Added ExportContextOptions interface and skipMissingReferences configuration property
lib/export/context/export-context-fetcher.ts	Updated state handling to use discriminated unions with skip state support
lib/translation/transforms/export-transforms.ts	Modified transforms to handle missing references using pattern matching and filtering
lib/translation/helpers/export-placeholder.utils.ts	New utility for generating placeholder text for missing references
lib/toolkit/migrate.ts	Added skipMissingReferences option to migration source configuration
lib/node/cli/commands.ts	Added CLI argument definition for skipMissingReferences parameter
lib/node/cli/actions/export-action.ts	Integrated skipMissingReferences parameter in export action
lib/node/cli/actions/migrate-action.ts	Integrated skipMissingReferences parameter in migrate action
lib/core/models/error.models.ts	New error class hierarchy with typed error categories
lib/core/models/core.models.ts	Refactored state types to use discriminated unions with data property
scripts/test/test-export.ts	Test script updated to use new skipMissingReferences option
scripts/test/import-report.json	Test result showing successful import with no errors
README.md	Documentation updated with new configuration parameter

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.