migrateEventEnvelope

@mineflow/contracts

---

@mineflow/contracts / migrateEventEnvelope

Function: migrateEventEnvelope()

function migrateEventEnvelope(envelope: object): object;

Defined in: event-migrator.ts:54

Приводит envelope к текущей версии события через миграцию из каталога.

Зачем: outbox + Redis Streams хранят envelopes неопределённо долго (DLQ retention, replay-сценарии). Breaking-change в data сразу ломает хендлеры на старых entries. С миграцией они конвертируются на лету в текущую схему до dispatch'а; handler видит только актуальную форму.

Контракт миграции: migrations[oldVersion] = (oldData) => dataShapedPerCurrentSchema

Для не-линейных bump'ов (1.0 → 3.0 минуя 2.0) пишите прямые миграции с каждой поддерживаемой from-версии — это явнее цепочки.

Что не делает:

• не трансформирует envelope-fields (id, type, occurredAt, …) — только data
• не двигает version назад (downgrade); только up-migration к current

Parameters

Parameter	Type	Description
envelope	{ causationId?: string; correlationId?: string; data: unknown; id: string; occurredAt: string; organizationId: string; producedBy: string; type: string; version: string; }	-
envelope.causationId?	string	UUID события-причины (опционально) — что инициировало это событие.
envelope.correlationId?	string	UUID цепочки корреляции (опционально) — связывает события одного бизнес-потока.
envelope.data	unknown	Полезная нагрузка события. unknown — форма задаётся type через eventCatalog. Дискриминируй по type и приводи к EventDataByName<'...'>.
envelope.id	string	UUID события (project-pattern, см. PROJECT_UUID_PATTERN).
envelope.occurredAt	string	Момент возникновения события, ISO 8601.
envelope.organizationId	string	UUID организации-владельца события (ADR-0020). Обязателен для всех бизнес-событий; обработчик при чтении из stream устанавливает OrgContext перед dispatch.
envelope.producedBy	string	Имя продюсера (сервис/модуль), записавшего событие.
envelope.type	string	Имя события <context>.<entity>.<verb-past>, напр. eam.asset.transferred.
envelope.version	string	Версия data-схемы в формате major.minor, напр. 1.0.

Returns

Name	Type	Default value	Description	Defined in
causationId?	string	-	UUID события-причины (опционально) — что инициировало это событие.	envelope.ts:50
correlationId?	string	-	UUID цепочки корреляции (опционально) — связывает события одного бизнес-потока.	envelope.ts:48
data	unknown	-	Полезная нагрузка события. unknown — форма задаётся type через eventCatalog. Дискриминируй по type и приводи к EventDataByName<'...'>.	envelope.ts:61
id	string	projectUuid	UUID события (project-pattern, см. PROJECT_UUID_PATTERN).	envelope.ts:38
occurredAt	string	-	Момент возникновения события, ISO 8601.	envelope.ts:44
organizationId	string	projectUuid	UUID организации-владельца события (ADR-0020). Обязателен для всех бизнес-событий; обработчик при чтении из stream устанавливает OrgContext перед dispatch.	envelope.ts:56
producedBy	string	-	Имя продюсера (сервис/модуль), записавшего событие.	envelope.ts:46
type	string	-	Имя события <context>.<entity>.<verb-past>, напр. eam.asset.transferred.	envelope.ts:40
version	string	-	Версия data-схемы в формате major.minor, напр. 1.0.	envelope.ts:42