@ably-labs/models/docs/event-correlation.md

<p align="left"> <a href=""> <img src="https://badgen.net/badge/development-status/alpha/yellow?icon=github" alt="Development status" /> </a> <a href=""> <img src="https://github.com/ably-labs/models/actions/workflows/dev-ci.yml/badge.svg?

# Event Correlation

*Event correlation* describes how the Models SDK matches unconfirmed, optimistic events with their confirmations received from the backend.

## Mutation IDs and comparator function

Optimistic and confirmed events are correlated using the mutation ID. The mutation ID is set on the optimistic event when it is created, and is expected to be set on the confirmed event emitted by your backend.

That means it's your responsibility to pass the mutation ID to your backend when making the mutation, so that it can be included in the confirmed event.

Whenever the library receives an event from the backend, it will compare it with the pending optimistic events using this function to determine whether the event is confirming a pending optimistic event.

Your backend should publish it's confirmation event with a special `x-ably-models-event-uuid` field in the `extras.headers`. If you are using [`adbc`](https://github.com/ably-labs/adbc/), this is achieved by setting the outbox record's `mutation_id`.

```ts
channel.publish({
	name: 'myEvent',
	data: { /* ... */ },
	extras: {
		headers: {
			'x-ably-models-event-uuid': mutationId,
		},
	},
});
```

When the Models SDK receives the confirmation event with the `x-ably-models-event-uuid` header, it will automatically correlate events using the uuid comparator:

```ts
export const uuidComparator: EventComparator = (optimistic: Event, confirmed: Event) => {
  return !!optimistic.uuid && !!confirmed.uuid && optimistic.uuid === confirmed.uuid;
};
```