@flusys/nestjs-event-manager 6.0.2 → 6.1.0

package/fesm/services/event.service.spec.js

@@ -0,0 +1,851 @@
+import { NotFoundException } from '@nestjs/common';
+import { ParticipantStatus, RecurrenceType } from '@flusys/nestjs-shared/enums';
+import { createMockRepository } from '@test-utils/mocks/repository.mock';
+import { buildMockUser } from '@test-utils/mocks/logged-user.mock';
+import { EVENT_MESSAGES, EVENT_PARTICIPANT_MESSAGES } from '../config';
+import { Event, EventParticipant, EventWithCompany } from '../entities';
+import { EventService } from './event.service';
+function buildEvent(overrides = {}) {
+    return {
+        id: 'event-uuid-1',
+        title: 'Sprint Planning',
+        description: null,
+        eventDate: '2026-04-03',
+        startTime: '09:00',
+        endTime: '10:00',
+        isAllDay: false,
+        recurrenceType: RecurrenceType.NONE,
+        recurrenceEndDate: null,
+        weekDays: null,
+        color: '#3B82F6',
+        meetingLink: null,
+        isActive: true,
+        createdAt: new Date('2026-01-01T00:00:00Z'),
+        updatedAt: new Date('2026-01-01T00:00:00Z'),
+        deletedAt: null,
+        createdById: null,
+        updatedById: null,
+        deletedById: null,
+        ...overrides
+    };
+}
+function buildParticipant(overrides = {}) {
+    return {
+        id: 'participant-uuid-1',
+        eventId: 'event-uuid-1',
+        userId: 'user-uuid-1',
+        status: ParticipantStatus.PENDING,
+        isOrganizer: false,
+        createdAt: new Date('2026-01-01T00:00:00Z'),
+        updatedAt: new Date('2026-01-01T00:00:00Z'),
+        deletedAt: null,
+        createdById: null,
+        updatedById: null,
+        deletedById: null,
+        ...overrides
+    };
+}
+describe('EventService', ()=>{
+    let service;
+    let mockEventRepo;
+    let mockParticipantRepo;
+    let mockConfigService;
+    let mockDataSourceProvider;
+    let mockEventQb;
+    const user = buildMockUser();
+    beforeEach(()=>{
+        mockEventRepo = createMockRepository();
+        mockParticipantRepo = createMockRepository();
+        mockEventQb = mockEventRepo.createQueryBuilder();
+        // `leftJoinAndMapMany` isn't part of the shared MockQueryBuilder.
+        mockEventQb.leftJoinAndMapMany = jest.fn().mockReturnThis();
+        mockConfigService = {
+            isCompanyFeatureEnabled: jest.fn().mockReturnValue(false),
+            getDefaultColor: jest.fn().mockReturnValue('#3B82F6'),
+            getMaxRecurrenceOccurrences: jest.fn().mockReturnValue(365)
+        };
+        mockDataSourceProvider = {
+            getRepository: jest.fn((entity)=>Promise.resolve(entity === EventParticipant ? mockParticipantRepo : mockEventRepo)),
+            getDataSource: jest.fn()
+        };
+        service = new EventService({}, {}, mockConfigService, mockDataSourceProvider);
+    });
+    describe('resolveEntity', ()=>{
+        it('resolves to the company-scoped entity when the company feature is enabled', ()=>{
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            expect(service.resolveEntity()).toBe(EventWithCompany);
+        });
+        it('resolves to the core entity when the company feature is disabled', ()=>{
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(false);
+            expect(service.resolveEntity()).toBe(Event);
+        });
+    });
+    describe('convertSingleDtoToEntity', ()=>{
+        it('builds a new entity with sensible defaults on create', async ()=>{
+            const dto = {
+                title: 'Sprint Planning',
+                eventDate: '2026-04-03',
+                startTime: '09:00',
+                endTime: '10:00'
+            };
+            const entity = await service.convertSingleDtoToEntity(dto, user);
+            expect(entity).toMatchObject({
+                title: 'Sprint Planning',
+                startTime: '09:00',
+                endTime: '10:00',
+                isAllDay: false,
+                recurrenceType: RecurrenceType.NONE,
+                recurrenceEndDate: null,
+                color: '#3B82F6',
+                isActive: true
+            });
+        });
+        it('forces 00:00 / 23:59 markers on create for all-day events', async ()=>{
+            const dto = {
+                title: 'Holiday',
+                eventDate: '2026-12-25',
+                startTime: '09:00',
+                endTime: '17:00',
+                isAllDay: true
+            };
+            const entity = await service.convertSingleDtoToEntity(dto, user);
+            expect(entity.startTime).toBe('00:00');
+            expect(entity.endTime).toBe('23:59');
+        });
+        it('attaches companyId from the current user when the company feature is enabled', async ()=>{
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            const dto = {
+                title: 'Sprint Planning',
+                eventDate: '2026-04-03',
+                startTime: '09:00',
+                endTime: '10:00'
+            };
+            const entity = await service.convertSingleDtoToEntity(dto, user);
+            expect(entity.companyId).toBe(user.companyId);
+        });
+        it('queues participantIds for the after-insert hook when supplied', async ()=>{
+            const dto = {
+                title: 'Sprint Planning',
+                eventDate: '2026-04-03',
+                startTime: '09:00',
+                endTime: '10:00',
+                participantIds: [
+                    'participant-uuid-1'
+                ]
+            };
+            await service.convertSingleDtoToEntity(dto, user);
+            expect(service.pendingParticipantsList).toEqual([
+                [
+                    'participant-uuid-1'
+                ]
+            ]);
+        });
+        it('merges an update dto onto the existing entity, preserving untouched fields', async ()=>{
+            service.repository = mockEventRepo;
+            const existing = buildEvent({
+                title: 'Original Title',
+                color: '#111111'
+            });
+            mockEventRepo.findOne.mockResolvedValue(existing);
+            const dto = {
+                id: 'event-uuid-1',
+                title: 'Updated Title'
+            };
+            const entity = await service.convertSingleDtoToEntity(dto, user);
+            expect(entity.title).toBe('Updated Title');
+            expect(entity.color).toBe('#111111');
+        });
+        it('throws NotFoundException with the correct messageKey when updating a missing event', async ()=>{
+            service.repository = mockEventRepo;
+            mockEventRepo.findOne.mockResolvedValue(null);
+            const dto = {
+                id: 'missing-uuid',
+                title: 'Updated Title'
+            };
+            await expect(service.convertSingleDtoToEntity(dto, user)).rejects.toMatchObject({
+                response: expect.objectContaining({
+                    messageKey: EVENT_MESSAGES.NOT_FOUND
+                })
+            });
+        });
+        it('clears an explicitly-null meetingLink but preserves the existing one when omitted', async ()=>{
+            service.repository = mockEventRepo;
+            const existing = buildEvent({
+                meetingLink: 'https://meet.example.com/original'
+            });
+            mockEventRepo.findOne.mockResolvedValue(existing);
+            const clearedDto = {
+                id: 'event-uuid-1',
+                meetingLink: null
+            };
+            const clearedEntity = await service.convertSingleDtoToEntity(clearedDto, user);
+            expect(clearedEntity.meetingLink).toBeNull();
+            const omittedDto = {
+                id: 'event-uuid-1'
+            };
+            const preservedEntity = await service.convertSingleDtoToEntity(omittedDto, user);
+            expect(preservedEntity.meetingLink).toBe('https://meet.example.com/original');
+        });
+    });
+    describe('getFilterQuery', ()=>{
+        it('filters by isActive when provided as a boolean', async ()=>{
+            const query = mockEventQb;
+            await service.getFilterQuery(query, {
+                isActive: true
+            }, user);
+            expect(query.andWhere).toHaveBeenCalledWith('event.isActive = :isActive', {
+                isActive: true
+            });
+        });
+        it('filters by recurrenceType', async ()=>{
+            const query = mockEventQb;
+            await service.getFilterQuery(query, {
+                recurrenceType: RecurrenceType.WEEKLY
+            }, user);
+            expect(query.andWhere).toHaveBeenCalledWith('event.recurrenceType = :recurrenceType', {
+                recurrenceType: RecurrenceType.WEEKLY
+            });
+        });
+        it('scopes to participant event ids when participantUserId is provided and matches exist', async ()=>{
+            const participantQb = mockParticipantRepo.createQueryBuilder();
+            participantQb.getRawMany = jest.fn().mockResolvedValue([
+                {
+                    ep_event_id: 'event-uuid-1'
+                }
+            ]);
+            const query = mockEventQb;
+            await service.getFilterQuery(query, {
+                participantUserId: 'user-uuid-1'
+            }, user);
+            expect(query.andWhere).toHaveBeenCalledWith('event.id IN (:...participantEventIds)', {
+                participantEventIds: [
+                    'event-uuid-1'
+                ]
+            });
+        });
+        it('short-circuits to an always-false predicate when the user participates in no events', async ()=>{
+            const participantQb = mockParticipantRepo.createQueryBuilder();
+            participantQb.getRawMany = jest.fn().mockResolvedValue([]);
+            const query = mockEventQb;
+            await service.getFilterQuery(query, {
+                participantUserId: 'user-uuid-1'
+            }, user);
+            expect(query.andWhere).toHaveBeenCalledWith('1 = 0');
+        });
+        it('falls back to an equality filter for unrecognized keys', async ()=>{
+            const query = mockEventQb;
+            await service.getFilterQuery(query, {
+                color: '#000000'
+            }, user);
+            expect(query.andWhere).toHaveBeenCalledWith('event.color = :value', {
+                value: '#000000'
+            });
+        });
+    });
+    describe('getExtraManipulateQuery', ()=>{
+        it('applies the company filter and left-joins participants', async ()=>{
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            const query = mockEventQb;
+            await service.getExtraManipulateQuery(query, {}, user);
+            expect(query.andWhere).toHaveBeenCalledWith('event.companyId = :companyId', {
+                companyId: user.companyId
+            });
+            expect(query.leftJoinAndMapMany).toHaveBeenCalledWith('event.participants', EventParticipant, 'ep', 'ep.event_id = event.id AND ep.deleted_at IS NULL');
+        });
+        it('does not apply a company filter when the company feature is disabled', async ()=>{
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(false);
+            const query = mockEventQb;
+            await service.getExtraManipulateQuery(query, {}, user);
+            const companyCalls = query.andWhere.mock.calls.filter((call)=>call[0] === 'event.companyId = :companyId');
+            expect(companyCalls).toHaveLength(0);
+        });
+    });
+    describe('afterInsertOperation / afterUpdateOperation', ()=>{
+        it('adds the current user and requested participants as organizer + attendees on insert', async ()=>{
+            mockParticipantRepo.find.mockResolvedValue([]);
+            mockParticipantRepo.save.mockResolvedValue([]);
+            service.pendingParticipantsList = [
+                [
+                    'participant-uuid-2'
+                ]
+            ];
+            await service.afterInsertOperation([
+                buildEvent()
+            ], {}, user, {});
+            const savedParticipants = mockParticipantRepo.save.mock.calls[0][0];
+            expect(savedParticipants).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    userId: user.id,
+                    isOrganizer: true
+                }),
+                expect.objectContaining({
+                    userId: 'participant-uuid-2',
+                    isOrganizer: false
+                })
+            ]));
+            expect(service.pendingParticipantsList).toEqual([]);
+        });
+        it('restores a previously soft-deleted participant instead of duplicating it', async ()=>{
+            const softDeleted = buildParticipant({
+                userId: user.id,
+                deletedAt: new Date()
+            });
+            mockParticipantRepo.find.mockResolvedValue([
+                softDeleted
+            ]);
+            mockParticipantRepo.save.mockResolvedValue([]);
+            service.pendingParticipantsList = [
+                []
+            ];
+            await service.afterInsertOperation([
+                buildEvent()
+            ], {}, user, {});
+            const savedParticipants = mockParticipantRepo.save.mock.calls[0][0];
+            expect(savedParticipants[0]).toMatchObject({
+                userId: user.id,
+                deletedAt: null,
+                isOrganizer: true
+            });
+        });
+        it('does nothing when there is no authenticated user', async ()=>{
+            service.pendingParticipantsList = [
+                [
+                    'participant-uuid-2'
+                ]
+            ];
+            await service.afterInsertOperation([
+                buildEvent()
+            ], {}, null, {});
+            expect(mockParticipantRepo.save).not.toHaveBeenCalled();
+        });
+        it('soft-deletes existing participants before re-adding the current set on update', async ()=>{
+            mockParticipantRepo.find.mockResolvedValue([]);
+            mockParticipantRepo.save.mockResolvedValue([]);
+            mockParticipantRepo.update.mockResolvedValue({});
+            service.pendingParticipantsList = [
+                [
+                    'participant-uuid-2'
+                ]
+            ];
+            await service.afterUpdateOperation([
+                buildEvent()
+            ], {}, user, {});
+            expect(mockParticipantRepo.update).toHaveBeenCalledWith({
+                eventId: 'event-uuid-1',
+                deletedAt: expect.anything()
+            }, {
+                deletedAt: expect.any(Date)
+            });
+            expect(mockParticipantRepo.save).toHaveBeenCalled();
+            expect(service.pendingParticipantsList).toEqual([]);
+        });
+    });
+    describe('updateParticipantStatus', ()=>{
+        it('updates the participant status and returns the saved entity', async ()=>{
+            const participant = buildParticipant({
+                status: ParticipantStatus.PENDING
+            });
+            mockParticipantRepo.findOne.mockResolvedValue(participant);
+            mockParticipantRepo.save.mockImplementation(async (p)=>p);
+            const dto = {
+                id: 'participant-uuid-1',
+                status: ParticipantStatus.TENTATIVE
+            };
+            const result = await service.updateParticipantStatus(dto, user);
+            expect(result.status).toBe(ParticipantStatus.TENTATIVE);
+            expect(mockParticipantRepo.save).toHaveBeenCalledWith(expect.objectContaining({
+                status: ParticipantStatus.TENTATIVE
+            }));
+        });
+        it('throws NotFoundException with the correct messageKey when the participant is missing', async ()=>{
+            mockParticipantRepo.findOne.mockResolvedValue(null);
+            const dto = {
+                id: 'missing-uuid',
+                status: ParticipantStatus.ACCEPTED
+            };
+            await expect(service.updateParticipantStatus(dto, user)).rejects.toMatchObject({
+                response: expect.objectContaining({
+                    messageKey: EVENT_PARTICIPANT_MESSAGES.NOT_FOUND
+                })
+            });
+            await expect(service.updateParticipantStatus(dto, user)).rejects.toBeInstanceOf(NotFoundException);
+        });
+    });
+    describe('getEventsForCalendarRange', ()=>{
+        function queryDto(overrides = {}) {
+            return {
+                startDate: '2026-04-01',
+                endDate: '2026-04-30',
+                ...overrides
+            };
+        }
+        it('returns a single non-recurring event unchanged when it falls in range', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-04-10'
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto(), user);
+            expect(result).toHaveLength(1);
+            expect(result[0].id).toBe('event-uuid-1');
+            expect(result[0].isRecurrenceInstance).toBeUndefined();
+        });
+        it('defaults activeOnly to true when not specified', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([]);
+            await service.getEventsForCalendarRange(queryDto(), user);
+            expect(mockEventQb.andWhere).toHaveBeenCalledWith('event.isActive = :isActive', {
+                isActive: true
+            });
+        });
+        it('respects activeOnly = false', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([]);
+            await service.getEventsForCalendarRange(queryDto({
+                activeOnly: false
+            }), user);
+            expect(mockEventQb.andWhere).toHaveBeenCalledWith('event.isActive = :isActive', {
+                isActive: false
+            });
+        });
+        it('handles a zero-length range (startDate === endDate)', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-04-10'
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-04-10',
+                endDate: '2026-04-10'
+            }), user);
+            expect(mockEventQb.andWhere).toHaveBeenCalledWith(expect.stringContaining('event.eventDate >= :startDate'), {
+                startDate: '2026-04-10',
+                endDate: '2026-04-10',
+                none: RecurrenceType.NONE
+            });
+            expect(result).toHaveLength(1);
+        });
+        it('short-circuits to an empty array when filtering by a userId with no participant events', async ()=>{
+            const participantQb = mockParticipantRepo.createQueryBuilder();
+            participantQb.getRawMany = jest.fn().mockResolvedValue([]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                userId: 'user-uuid-1'
+            }), user);
+            expect(result).toEqual([]);
+            expect(mockEventQb.getMany).not.toHaveBeenCalled();
+        });
+        it('filters events to the participant event ids when userId matches events', async ()=>{
+            const participantQb = mockParticipantRepo.createQueryBuilder();
+            participantQb.getRawMany = jest.fn().mockResolvedValue([
+                {
+                    ep_event_id: 'event-uuid-1'
+                }
+            ]);
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent()
+            ]);
+            await service.getEventsForCalendarRange(queryDto({
+                userId: 'user-uuid-1'
+            }), user);
+            expect(mockEventQb.andWhere).toHaveBeenCalledWith('event.id IN (:...eventIds)', {
+                eventIds: [
+                    'event-uuid-1'
+                ]
+            });
+        });
+        it('loads and attaches participants when includeParticipants is true', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent()
+            ]);
+            mockParticipantRepo.find.mockResolvedValue([
+                buildParticipant({
+                    eventId: 'event-uuid-1',
+                    userId: 'user-uuid-1'
+                }),
+                buildParticipant({
+                    id: 'participant-uuid-2',
+                    eventId: 'event-uuid-1',
+                    userId: 'user-uuid-2'
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                includeParticipants: true
+            }), user);
+            expect(result[0].participants).toHaveLength(2);
+            expect(result[0].participants?.[0].userId).toBe('user-uuid-1');
+        });
+        it('does not query participants when includeParticipants is falsy', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent()
+            ]);
+            await service.getEventsForCalendarRange(queryDto(), user);
+            expect(mockParticipantRepo.find).not.toHaveBeenCalled();
+        });
+        it('does not query participants when there are no events to attach them to', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([]);
+            await service.getEventsForCalendarRange(queryDto({
+                includeParticipants: true
+            }), user);
+            expect(mockParticipantRepo.find).not.toHaveBeenCalled();
+        });
+        // ---------------------------------------------------------------------
+        // Recurrence expansion — daily
+        // ---------------------------------------------------------------------
+        it('expands an infinite daily recurrence within the range, marking only the first occurrence as non-instance', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-01-01',
+                    recurrenceType: RecurrenceType.DAILY
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-01-01',
+                endDate: '2026-01-05'
+            }), user);
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2026-01-01',
+                '2026-01-02',
+                '2026-01-03',
+                '2026-01-04',
+                '2026-01-05'
+            ]);
+            expect(result[0].isRecurrenceInstance).toBe(false);
+            expect(result.slice(1).every((e)=>e.isRecurrenceInstance === true)).toBe(true);
+            expect(result.every((e)=>e.originalEventId === 'event-uuid-1')).toBe(true);
+            expect(result[1].id).toBe('event-uuid-1_2026-01-02');
+        });
+        it('stops a daily recurrence at the until (recurrenceEndDate) bound, before the range end', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-01-01',
+                    recurrenceType: RecurrenceType.DAILY,
+                    recurrenceEndDate: '2026-01-03'
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-01-01',
+                endDate: '2026-01-10'
+            }), user);
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2026-01-01',
+                '2026-01-02',
+                '2026-01-03'
+            ]);
+        });
+        it('caps a count-based (no end date) recurrence at the configured max occurrences', async ()=>{
+            mockConfigService.getMaxRecurrenceOccurrences.mockReturnValue(3);
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-01-01',
+                    recurrenceType: RecurrenceType.DAILY
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-01-01',
+                endDate: '2026-12-31'
+            }), user);
+            expect(result).toHaveLength(3);
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2026-01-01',
+                '2026-01-02',
+                '2026-01-03'
+            ]);
+        });
+        it('returns a single occurrence when the recurrence range only covers the start date', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-01-01',
+                    recurrenceType: RecurrenceType.DAILY
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-01-01',
+                endDate: '2026-01-01'
+            }), user);
+            expect(result).toHaveLength(1);
+            expect(result[0].eventDate).toBe('2026-01-01');
+        });
+        it('produces no occurrences when the query range is entirely before the series start', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-06-01',
+                    recurrenceType: RecurrenceType.DAILY,
+                    recurrenceEndDate: '2026-06-10'
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-01-01',
+                endDate: '2026-01-31'
+            }), user);
+            expect(result).toEqual([]);
+        });
+        it('does not shift dates across a US daylight-saving boundary (spring-forward, 2026-03-08)', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-03-06',
+                    recurrenceType: RecurrenceType.DAILY
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-03-06',
+                endDate: '2026-03-10'
+            }), user);
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2026-03-06',
+                '2026-03-07',
+                '2026-03-08',
+                '2026-03-09',
+                '2026-03-10'
+            ]);
+        });
+        it('does not shift dates across a US daylight-saving boundary (fall-back, 2026-11-01)', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-10-30',
+                    recurrenceType: RecurrenceType.DAILY
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-10-30',
+                endDate: '2026-11-03'
+            }), user);
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2026-10-30',
+                '2026-10-31',
+                '2026-11-01',
+                '2026-11-02',
+                '2026-11-03'
+            ]);
+        });
+        // ---------------------------------------------------------------------
+        // Recurrence expansion — weekly / biweekly
+        // ---------------------------------------------------------------------
+        it('expands a weekly recurrence using the event own weekday when weekDays is not set', async ()=>{
+            // 2026-01-05 is a Monday
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-01-05',
+                    recurrenceType: RecurrenceType.WEEKLY,
+                    weekDays: null
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-01-05',
+                endDate: '2026-01-26'
+            }), user);
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2026-01-05',
+                '2026-01-12',
+                '2026-01-19',
+                '2026-01-26'
+            ]);
+        });
+        it('expands a weekly recurrence across multiple weekDays', async ()=>{
+            // 2026-01-05 is a Monday; weekDays MON + WED
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-01-05',
+                    recurrenceType: RecurrenceType.WEEKLY,
+                    weekDays: [
+                        'MON',
+                        'WED'
+                    ]
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-01-01',
+                endDate: '2026-01-14'
+            }), user);
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2026-01-05',
+                '2026-01-07',
+                '2026-01-12',
+                '2026-01-14'
+            ]);
+            expect(result[0].isRecurrenceInstance).toBe(false);
+            expect(result.slice(1).every((e)=>e.isRecurrenceInstance === true)).toBe(true);
+        });
+        it('skips a weekday occurrence that falls before the series start date in its first week', async ()=>{
+            // 2026-01-07 is a Wednesday; the same week's Monday (Jan 5) is before the series
+            // start and must not produce an occurrence, but later weeks' Mondays should.
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-01-07',
+                    recurrenceType: RecurrenceType.WEEKLY,
+                    weekDays: [
+                        'MON',
+                        'WED'
+                    ]
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-01-01',
+                endDate: '2026-01-21'
+            }), user);
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2026-01-07',
+                '2026-01-12',
+                '2026-01-14',
+                '2026-01-19',
+                '2026-01-21'
+            ]);
+        });
+        it('expands a biweekly recurrence with two-week spacing', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-01-05',
+                    recurrenceType: RecurrenceType.BIWEEKLY,
+                    weekDays: null
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-01-05',
+                endDate: '2026-02-28'
+            }), user);
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2026-01-05',
+                '2026-01-19',
+                '2026-02-02',
+                '2026-02-16'
+            ]);
+        });
+        it('stops a weekly recurrence at the until bound mid-week', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-01-05',
+                    recurrenceType: RecurrenceType.WEEKLY,
+                    weekDays: null,
+                    recurrenceEndDate: '2026-01-12'
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-01-01',
+                endDate: '2026-01-31'
+            }), user);
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2026-01-05',
+                '2026-01-12'
+            ]);
+        });
+        // ---------------------------------------------------------------------
+        // Recurrence expansion — monthly
+        // ---------------------------------------------------------------------
+        it('expands a monthly recurrence, clamping to the last day of shorter months', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-01-31',
+                    recurrenceType: RecurrenceType.MONTHLY
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-01-01',
+                endDate: '2026-04-30'
+            }), user);
+            // 2026 is not a leap year: Feb has 28 days; Mar has 31 (back to day 31); Apr has 30.
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2026-01-31',
+                '2026-02-28',
+                '2026-03-31',
+                '2026-04-30'
+            ]);
+        });
+        it('restores the original day-of-month once a longer month is reached again', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-01-31',
+                    recurrenceType: RecurrenceType.MONTHLY
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-02-01',
+                endDate: '2026-03-31'
+            }), user);
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2026-02-28',
+                '2026-03-31'
+            ]);
+        });
+        it('clamps to Feb 29 on a leap year for a monthly recurrence starting Jan 31', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2028-01-31',
+                    recurrenceType: RecurrenceType.MONTHLY
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2028-01-01',
+                endDate: '2028-02-29'
+            }), user);
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2028-01-31',
+                '2028-02-29'
+            ]);
+        });
+        // ---------------------------------------------------------------------
+        // All-day events
+        // ---------------------------------------------------------------------
+        it('preserves isAllDay through non-recurring expansion', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-04-10',
+                    isAllDay: true,
+                    startTime: '00:00',
+                    endTime: '23:59'
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto(), user);
+            expect(result[0].isAllDay).toBe(true);
+            expect(result[0].startTime).toBe('00:00');
+            expect(result[0].endTime).toBe('23:59');
+        });
+        it('preserves isAllDay through recurring expansion', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    eventDate: '2026-01-01',
+                    recurrenceType: RecurrenceType.DAILY,
+                    isAllDay: true,
+                    startTime: '00:00',
+                    endTime: '23:59'
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-01-01',
+                endDate: '2026-01-02'
+            }), user);
+            expect(result.every((e)=>e.isAllDay === true)).toBe(true);
+        });
+        // ---------------------------------------------------------------------
+        // Sorting and multi-event ordering
+        // ---------------------------------------------------------------------
+        it('returns events sorted chronologically by eventDate, including expanded recurrence instances', async ()=>{
+            mockEventQb.getMany.mockResolvedValue([
+                buildEvent({
+                    id: 'event-b',
+                    eventDate: '2026-01-03',
+                    recurrenceType: RecurrenceType.NONE
+                }),
+                buildEvent({
+                    id: 'event-a',
+                    eventDate: '2026-01-01',
+                    recurrenceType: RecurrenceType.DAILY,
+                    recurrenceEndDate: '2026-01-02'
+                })
+            ]);
+            const result = await service.getEventsForCalendarRange(queryDto({
+                startDate: '2026-01-01',
+                endDate: '2026-01-05'
+            }), user);
+            expect(result.map((e)=>e.eventDate)).toEqual([
+                '2026-01-01',
+                '2026-01-02',
+                '2026-01-03'
+            ]);
+        });
+    });
+    describe('ensureParticipantRepositoryInitialized', ()=>{
+        it('caches the participant repository after the first resolution', async ()=>{
+            await service.ensureParticipantRepositoryInitialized();
+            await service.ensureParticipantRepositoryInitialized();
+            expect(mockDataSourceProvider.getRepository).toHaveBeenCalledTimes(1);
+            expect(mockDataSourceProvider.getRepository).toHaveBeenCalledWith(EventParticipant);
+        });
+    });
+});