|
1 | 1 | # Upgrading Guide |
2 | 2 |
|
| 3 | +## Upgrading </br> `core` `25.x.x` -> `26.0.0` </br> `sqs` `xx.x.x` -> `xx.0.0` </br> `sns` `xx.x.x` -> `xx.0.0` </br> `amqp` `xx.x.x` -> `xx.0.0` </br> `gcp-pubsub` `2.x.x` -> `3.0.0` |
| 4 | + |
| 5 | +### Description of Breaking Changes |
| 6 | + |
| 7 | +- **`messageTypeField` option removed**: The deprecated `messageTypeField` option has been removed from all queue services. Use `messageTypeResolver` instead. |
| 8 | + |
| 9 | +- **`HandlerSpyParams.messageTypePath` removed**: The `messageTypePath` option in `HandlerSpyParams` has been removed. Message types are now passed explicitly when adding processed messages. This is handled internally by the library, so most users won't need to make changes. |
| 10 | + |
| 11 | +### Migration Steps |
| 12 | + |
| 13 | +#### Replacing `messageTypeField` with `messageTypeResolver` |
| 14 | + |
| 15 | +Replace `messageTypeField: 'fieldName'` with `messageTypeResolver: { messageTypePath: 'fieldName' }`: |
| 16 | + |
| 17 | +```typescript |
| 18 | +// Before |
| 19 | +super(dependencies, { |
| 20 | + messageTypeField: 'type', |
| 21 | + handlers: new MessageHandlerConfigBuilder() |
| 22 | + .addConfig(schema, handler) |
| 23 | + .build(), |
| 24 | +}) |
| 25 | + |
| 26 | +// After |
| 27 | +super(dependencies, { |
| 28 | + messageTypeResolver: { messageTypePath: 'type' }, |
| 29 | + handlers: new MessageHandlerConfigBuilder() |
| 30 | + .addConfig(schema, handler) |
| 31 | + .build(), |
| 32 | +}) |
| 33 | +``` |
| 34 | + |
| 35 | +## Upgrading </br> `core` `24.x.x` -> `25.0.0` </br> `gcp-pubsub` `1.x.x` -> `2.0.0` |
| 36 | + |
| 37 | +### Description of Breaking Changes |
| 38 | + |
| 39 | +- **`NO_MESSAGE_TYPE_FIELD` constant removed**: The `NO_MESSAGE_TYPE_FIELD` constant has been removed from `@message-queue-toolkit/core`. Use `messageTypeResolver` with literal mode instead. |
| 40 | + |
| 41 | +- **New `messageTypeResolver` configuration**: A flexible configuration for message type resolution. Supports three modes: |
| 42 | + - `{ messageTypePath: 'type' }` - extract type from a field at the root of the message |
| 43 | + - `{ literal: 'my.message.type' }` - use a constant type for all messages |
| 44 | + - `{ resolver: ({ messageData, messageAttributes }) => 'resolved.type' }` - custom resolver function |
| 45 | + |
| 46 | +- **Explicit `messageType` in handler configuration**: When using a custom resolver function, you must provide an explicit `messageType` in handler options since the type cannot be extracted from schemas at registration time. |
| 47 | + |
| 48 | +### Migration Steps |
| 49 | + |
| 50 | +#### If using `NO_MESSAGE_TYPE_FIELD` |
| 51 | + |
| 52 | +Replace `messageTypeField: NO_MESSAGE_TYPE_FIELD` with `messageTypeResolver: { literal: 'your.message.type' }`: |
| 53 | + |
| 54 | +```typescript |
| 55 | +// Before |
| 56 | +import { NO_MESSAGE_TYPE_FIELD } from '@message-queue-toolkit/core' |
| 57 | + |
| 58 | +super(dependencies, { |
| 59 | + messageTypeField: NO_MESSAGE_TYPE_FIELD, |
| 60 | + handlers: new MessageHandlerConfigBuilder() |
| 61 | + .addConfig(schema, handler) |
| 62 | + .build(), |
| 63 | +}) |
| 64 | + |
| 65 | +// After |
| 66 | +super(dependencies, { |
| 67 | + messageTypeResolver: { literal: 'your.message.type' }, |
| 68 | + handlers: new MessageHandlerConfigBuilder() |
| 69 | + .addConfig(schema, handler, { messageType: 'your.message.type' }) |
| 70 | + .build(), |
| 71 | +}) |
| 72 | +``` |
| 73 | + |
| 74 | +#### If using custom resolver function |
| 75 | + |
| 76 | +When using `messageTypeResolver: { resolver: fn }`, provide explicit `messageType` in handler options: |
| 77 | + |
| 78 | +```typescript |
| 79 | +super(dependencies, { |
| 80 | + messageTypeResolver: { |
| 81 | + resolver: ({ messageAttributes }) => { |
| 82 | + // Map external event types to internal types |
| 83 | + const eventType = messageAttributes?.eventType as string |
| 84 | + if (eventType === 'OBJECT_FINALIZE') return 'storage.object.created' |
| 85 | + throw new Error(`Unknown event type: ${eventType}`) |
| 86 | + }, |
| 87 | + }, |
| 88 | + handlers: new MessageHandlerConfigBuilder() |
| 89 | + .addConfig(ObjectSchema, handler, { messageType: 'storage.object.created' }) |
| 90 | + .build(), |
| 91 | +}) |
| 92 | +``` |
| 93 | + |
| 94 | +#### GCP Pub/Sub DLQ Consumer |
| 95 | + |
| 96 | +The `AbstractPubSubDlqConsumer` now uses `DLQ_MESSAGE_TYPE` constant internally. If you import this constant, update your import: |
| 97 | + |
| 98 | +```typescript |
| 99 | +import { DLQ_MESSAGE_TYPE } from '@message-queue-toolkit/gcp-pubsub' |
| 100 | +// DLQ_MESSAGE_TYPE = 'dlq.message' |
| 101 | +``` |
| 102 | + |
3 | 103 | ## Upgrading </br> `core` `19.0.0` -> `20.0.0` </br> `sqs` `19.0.0` -> `20.0.0` </br> `sns` `20.0.0` -> `21.0.0` </br> `amqp` `18.0.0` -> `19.0.0` </br> `metrics` `2.0.0` -> `3.0.0` |
4 | 104 |
|
5 | 105 | ### Description of Breaking Changes |
|
0 commit comments