Migrate Events -> SC Hooks (#3548)

CarsonF · web-flow · commit b7daeb86e7d0 · 2025-08-26T08:02:22.000-05:00
Begins move from `~/core/events` to `~/core/hooks` which is just the rebranded v2 of _events_ that is in our library. I swapped out the underlying implementation here for the hooks module, and gave a few migration examples. But I left most of the old code as deprecated for future clean up. In general we are just renaming: - `events/` -> `hooks/` - `XEvent` -> `XHook` - `IEventBus` -> `Hooks` - `@EventHandler(...)` -> `@OnHook(...)` Only real change, is the priority ordering is flipped, so lower numbers come first now. So just flip the sign of the priority declared in decorator. More info here: SeedCompany/libs#60
diff --git a/.eslintrc.cjs b/.eslintrc.cjs
@@ -103,6 +103,11 @@ const restrictedImports = [
     path: 'gql.tada',
     replacement: { path: '~/graphql' },
   },
+  {
+    path: '@seedcompany/nest/hooks',
+    replacement: { path: '~/core/hooks' },
+    message: 'Reference from core instead to keep loose coupling',
+  },
 ];
 
 const namingConvention = [
diff --git a/src/components/authorization/authorization.module.ts b/src/components/authorization/authorization.module.ts
@@ -7,7 +7,7 @@ import {
   SessionExtraInfoResolver,
 } from './authorization.resolver';
 import { BetaFeaturesGranter } from './dto/beta-features.dto';
-import { CanImpersonateHandler } from './handler/can-impersonate.handler';
+import { CanImpersonateViaPrivilegesHandler } from './handler/can-impersonate-via-privileges.handler';
 import * as Policies from './policies';
 import { PolicyModule } from './policy/policy.module';
 
@@ -19,7 +19,7 @@ import { PolicyModule } from './policy/policy.module';
     LoginExtraInfoResolver,
     RegisterExtraInfoResolver,
     SessionExtraInfoResolver,
-    CanImpersonateHandler,
+    CanImpersonateViaPrivilegesHandler,
     ...Object.values(Policies),
     AssignableRolesGranter,
     BetaFeaturesGranter,
diff --git a/src/components/authorization/handler/can-impersonate-via-privileges.handler.ts b/src/components/authorization/handler/can-impersonate-via-privileges.handler.ts
@@ -0,0 +1,17 @@
+import { Injectable } from '@nestjs/common';
+import { CanImpersonateHook } from '~/core/authentication/hooks/can-impersonate.hook';
+import { OnHook } from '~/core/hooks';
+import { AssignableRoles } from '../dto/assignable-roles.dto';
+import { Privileges } from '../policy';
+
+@Injectable()
+export class CanImpersonateViaPrivilegesHandler {
+  constructor(private readonly privileges: Privileges) {}
+
+  @OnHook(CanImpersonateHook)
+  canImpersonate({ session, allow }: CanImpersonateHook) {
+    const p = this.privileges.for(AssignableRoles);
+    const granted = session.roles.values().every((role) => p.can('edit', role));
+    allow.vote(granted);
+  }
+}
diff --git a/src/components/authorization/handler/can-impersonate.handler.ts b/src/components/authorization/handler/can-impersonate.handler.ts
diff --git a/src/components/engagement/handlers/validate-eng-date-overrides-on-project-change.handler.ts b/src/components/engagement/handlers/validate-eng-date-overrides-on-project-change.handler.ts
@@ -1,14 +1,14 @@
+import { Injectable } from '@nestjs/common';
 import { DateOverrideConflictException, EnhancedResource } from '~/common';
-import { EventsHandler, type IEventHandler } from '~/core';
+import { OnHook } from '~/core/hooks';
 import { ProjectUpdatedEvent } from '../../project/events';
 import { EngagementService } from '../engagement.service';
 
-@EventsHandler([ProjectUpdatedEvent, 10])
-export class ValidateEngDateOverridesOnProjectChangeHandler
-  implements IEventHandler<ProjectUpdatedEvent>
-{
+@Injectable()
+export class ValidateEngDateOverridesOnProjectChangeHandler {
   constructor(private readonly engagements: EngagementService) {}
 
+  @OnHook(ProjectUpdatedEvent, -10)
   async handle(event: ProjectUpdatedEvent) {
     const { updated: project, changes } = event;
 
diff --git a/src/components/periodic-report/handlers/sync-progress-report-to-engagement.handler.ts b/src/components/periodic-report/handlers/sync-progress-report-to-engagement.handler.ts
@@ -1,6 +1,8 @@
+import { Injectable } from '@nestjs/common';
 import { Settings } from 'luxon';
 import { DateInterval, type UnsecuredDto } from '~/common';
-import { EventsHandler, type IEventHandler, ILogger, Logger } from '~/core';
+import { ILogger, Logger } from '~/core';
+import { OnHook } from '~/core/hooks';
 import { EngagementService } from '../../engagement';
 import { type Engagement, engagementRange } from '../../engagement/dto';
 import {
@@ -15,20 +17,8 @@ import {
   type Intervals,
 } from './abstract-periodic-report-sync';
 
-type SubscribedEvent =
-  | EngagementCreatedEvent
-  | EngagementUpdatedEvent
-  | ProjectUpdatedEvent;
-
-@EventsHandler(
-  EngagementCreatedEvent,
-  EngagementUpdatedEvent,
-  ProjectUpdatedEvent,
-)
-export class SyncProgressReportToEngagementDateRange
-  extends AbstractPeriodicReportSync
-  implements IEventHandler<SubscribedEvent>
-{
+@Injectable()
+export class SyncProgressReportToEngagementDateRange extends AbstractPeriodicReportSync {
   constructor(
     periodicReports: PeriodicReportService,
     private readonly engagements: EngagementService,
@@ -37,7 +27,15 @@ export class SyncProgressReportToEngagementDateRange
     super(periodicReports);
   }
 
-  async handle(event: SubscribedEvent) {
+  @OnHook(EngagementCreatedEvent)
+  @OnHook(EngagementUpdatedEvent)
+  @OnHook(ProjectUpdatedEvent)
+  async handle(
+    event:
+      | EngagementCreatedEvent
+      | EngagementUpdatedEvent
+      | ProjectUpdatedEvent,
+  ) {
     // Only LanguageEngagements
     if (
       !(
diff --git a/src/core/authentication/hooks/can-impersonate.hook.ts b/src/core/authentication/hooks/can-impersonate.hook.ts
@@ -1,6 +1,6 @@
 import { type PollVoter } from '~/common';
 import { type Session } from '../session/session.dto';
 
-export class CanImpersonateEvent {
+export class CanImpersonateHook {
   constructor(readonly session: Session, readonly allow: PollVoter<boolean>) {}
 }
diff --git a/src/core/authentication/session/session.manager.ts b/src/core/authentication/session/session.manager.ts
@@ -9,11 +9,11 @@ import {
   ServerException,
   UnauthorizedException,
 } from '~/common';
-import { IEventBus } from '~/core/events';
+import { Hooks } from '~/core/hooks';
 import { ILogger, Logger } from '~/core/logger';
 import { SystemAgentRepository } from '../../../components/user/system-agent.repository';
 import { AuthenticationRepository } from '../authentication.repository';
-import { CanImpersonateEvent } from '../events/can-impersonate.event';
+import { CanImpersonateHook } from '../hooks/can-impersonate.hook';
 import { JwtService } from '../jwt.service';
 import { NoSessionException } from './no-session.exception';
 import { Session } from './session.dto';
@@ -26,7 +26,7 @@ import { SessionHost } from './session.host';
 export class SessionManager {
   constructor(
     private readonly agents: SystemAgentRepository,
-    private readonly events: IEventBus,
+    private readonly hooks: Hooks,
     private readonly jwt: JwtService,
     private readonly sessionHost: SessionHost,
     private readonly repo: AuthenticationRepository,
@@ -105,11 +105,11 @@ export class SessionManager {
     if (impersonatee) {
       const allowImpersonation = new Poll();
       await this.sessionHost.withSession(requesterSession, async () => {
-        const event = new CanImpersonateEvent(
+        const event = new CanImpersonateHook(
           requesterSession,
           allowImpersonation,
         );
-        await this.events.publish(event);
+        await this.hooks.run(event);
       });
       if (!(allowImpersonation.plurality && !allowImpersonation.vetoed)) {
         // Don't expose what the requester is unable to do as this could leak
diff --git a/src/core/core.module.ts b/src/core/core.module.ts
@@ -2,6 +2,8 @@ import { Global, Module } from '@nestjs/common';
 import { APP_FILTER, APP_INTERCEPTOR } from '@nestjs/core';
 import { DataLoaderModule } from '@seedcompany/data-loader';
 import { DiscoveryModule } from '@seedcompany/nest/discovery';
+// eslint-disable-next-line @seedcompany/no-restricted-imports
+import { HooksModule } from '@seedcompany/nest/hooks';
 import { EmailModule } from '@seedcompany/nestjs-email';
 import { AuthenticationModule } from './authentication/authentication.module';
 import { AwsS3Factory } from './aws-s3.factory';
@@ -38,6 +40,7 @@ import { WaitResolver } from './wait.resolver';
     GelModule,
     EmailModule.forRootAsync({ useExisting: ConfigService }),
     DiscoveryModule,
+    HooksModule,
     GraphqlModule,
     EventsModule,
     TracingModule,
@@ -65,6 +68,7 @@ import { WaitResolver } from './wait.resolver';
     DatabaseModule,
     DataLoaderModule,
     DiscoveryModule,
+    HooksModule,
     GelModule,
     EmailModule,
     EventsModule,
diff --git a/src/core/events/constants.ts b/src/core/events/constants.ts
diff --git a/src/core/events/event-bus.service.ts b/src/core/events/event-bus.service.ts
@@ -1,91 +1,21 @@
-import { Injectable, type OnApplicationBootstrap } from '@nestjs/common';
-import {
-  type FnLike,
-  groupToMapBy,
-  mapValues,
-  sortBy,
-} from '@seedcompany/common';
-import { stripIndent } from 'common-tags';
-import { type ID, ServerException } from '~/common';
-import { MetadataDiscovery } from '~/core/discovery';
-import { ILogger, Logger } from '../logger';
-import { EVENT_METADATA } from './constants';
-import { EventsHandler, type IEventHandler } from './event-handler.decorator';
+import { Injectable } from '@nestjs/common';
+import { Hooks } from '../hooks';
 
 /**
  * An event bus for internal use.
  * This should be used to de-couple logic between different modules.
+ *
+ * @deprecated use {@link Hooks} instead.
  */
-export abstract class IEventBus {
-  publish: (event: object) => Promise<void>;
-  publishAll: (events: object[]) => Promise<void>;
-}
-
 @Injectable()
-export class SyncEventBus implements IEventBus, OnApplicationBootstrap {
-  private listenerMap: Record<ID, FnLike[]> = {};
-
-  constructor(
-    private readonly discovery: MetadataDiscovery,
-    @Logger('event-bus') private readonly logger: ILogger,
-  ) {}
+export class IEventBus {
+  constructor(private readonly hooks: Hooks) {}
 
   async publish(event: object): Promise<void> {
-    let id;
-    try {
-      id = Reflect.getMetadata(EVENT_METADATA, event.constructor).id;
-    } catch (e) {
-      // Fails when event doesn't have an ID in its metadata,
-      // which is created upon first registration with a handler.
-      if (process.env.NODE_ENV === 'production') {
-        return;
-      }
-      this.logger.warning(
-        `It appears that ${event.constructor.name} does not have any registered handlers. Are you sure this is right?`,
-      );
-      return;
-    }
-    for (const handler of this.listenerMap[id] || []) {
-      await handler(event);
-    }
+    await this.hooks.run(event);
   }
 
   async publishAll(events: any[]): Promise<void> {
     await Promise.all(events.map((e) => this.publish(e)));
   }
-
-  async onApplicationBootstrap() {
-    const discovered = this.discovery
-      .discover(EventsHandler)
-      .classes<IEventHandler<any>>();
-
-    if (process.env.NODE_ENV !== 'production') {
-      const defined = new Set<string>();
-      for (const entry of discovered) {
-        const name = entry.instance.constructor.name;
-        if (defined.has(name)) {
-          throw new ServerException(stripIndent`
-            Event handler "${name}" has already been defined.
-            Event handlers have to have unique class names for DX sanity.
-          `);
-        }
-        defined.add(name);
-      }
-    }
-
-    const flat = discovered.flatMap(({ instance, meta }) => {
-      const handler = instance.handle.bind(instance);
-      return [...meta].map(([id, priority]) => ({
-        id,
-        priority,
-        handler,
-      }));
-    });
-    const grouped = groupToMapBy(flat, (entry) => entry.id);
-    this.listenerMap = mapValues(grouped, (_, entries) =>
-      sortBy(entries, [(entry) => entry.priority, 'desc']).map(
-        (e) => e.handler,
-      ),
-    ).asRecord;
-  }
 }
diff --git a/src/core/events/event-handler.decorator.ts b/src/core/events/event-handler.decorator.ts
@@ -1,8 +1,5 @@
 import { type Type } from '@nestjs/common';
-import { createMetadataDecorator } from '@seedcompany/nest';
-import { nanoid } from 'nanoid';
-import { type ID } from '~/common';
-import { EVENT_METADATA, type Priority } from './constants';
+import { OnHook } from '../hooks';
 
 /**
  * Subscribe to these given events.
@@ -20,41 +17,33 @@ import { EVENT_METADATA, type Priority } from './constants';
  *   Event2
  * )
  * ```
+ *
+ * @deprecated use {@link OnHook} instead.
  */
-export const EventsHandler = createMetadataDecorator({
-  types: ['class'],
-  setter: (...events: Array<Type | [...Type[], Priority]>) => {
-    const metadata = new Map<ID, Priority>();
-
+export const EventsHandler =
+  (...events: Array<Type | [...Type[], priority: number]>): ClassDecorator =>
+  (target) => {
     for (const arg of events) {
-      let priority: Priority = 0;
+      let priority = 0;
       let eventTypes: Type[] = [];
       if (!Array.isArray(arg)) {
         eventTypes = [arg];
       } else {
-        priority = arg.pop() as Priority;
+        priority = arg.pop() as number;
         eventTypes = arg as Type[];
       }
 
       for (const event of eventTypes) {
-        metadata.set(getOrDefineEventId(event), priority);
+        OnHook(event, priority * -1)(target);
       }
     }
+  };
 
-    return metadata;
-  },
-});
-
+/**
+ * @deprecated IMO this adds little value. It is just a small hint
+ * that "hey this class's handle() method is called indirectly".
+ */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export interface IEventHandler<T> {
   handle: (event: T) => Promise<void>;
 }
-
-const getOrDefineEventId = (event: Type): ID => {
-  if (!Reflect.hasMetadata(EVENT_METADATA, event)) {
-    const id: ID = nanoid();
-    Reflect.defineMetadata(EVENT_METADATA, { id }, event);
-    return id;
-  }
-  return Reflect.getMetadata(EVENT_METADATA, event).id;
-};
diff --git a/src/core/events/events.module.ts b/src/core/events/events.module.ts
@@ -1,8 +1,8 @@
 import { Module } from '@nestjs/common';
-import { IEventBus, SyncEventBus } from './event-bus.service';
+import { IEventBus } from './event-bus.service';
 
 @Module({
-  providers: [SyncEventBus, { provide: IEventBus, useExisting: SyncEventBus }],
+  providers: [IEventBus],
   exports: [IEventBus],
 })
 export class EventsModule {}
diff --git a/src/core/hooks/index.ts b/src/core/hooks/index.ts
@@ -0,0 +1,2 @@
+// eslint-disable-next-line @seedcompany/no-restricted-imports
+export { Hooks, OnHook } from '@seedcompany/nest/hooks';

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`import { type PollVoter } from '~/common';`
`2`	`2`	`import { type Session } from '../session/session.dto';`
`3`	`3`
`4`		`-export class CanImpersonateEvent {`
	`4`	`+export class CanImpersonateHook {`
`5`	`5`	`constructor(readonly session: Session, readonly allow: PollVoter<boolean>) {}`
`6`	`6`	`}`