@pattern-stack/codegen 0.18.0 → 0.20.0

package/runtime/subsystems/events/events-errors.ts

@@ -28,3 +28,17 @@ export class MissingTenantIdError extends Error {
     );
   }
 }
+
+/**
+ * Thrown (ADR-039) when a scheduled event's `schedule` config is invalid at
+ * runtime — a malformed `schedule.every` duration, or a scheduled event with no
+ * direction/pool to route by. Codegen validates `schedule` at `gen-all` time;
+ * this is the boot backstop for a hand-edited registry or version skew. Raised
+ * by `EventScheduler` construction / `parseEvery`.
+ */
+export class ScheduleConfigError extends Error {
+  override readonly name = 'ScheduleConfigError';
+  constructor(message: string) {
+    super(`ScheduleConfigError: ${message}`);
+  }
+}

package/runtime/subsystems/events/events.module.ts

@@ -44,7 +44,18 @@
  * `new Class()` which silently left `db` / `redisUrl` undefined
  * (issue #108).
  */
-import { Module, type DynamicModule, type Provider, type Type } from '@nestjs/common';
+import {
+  Inject,
+  Injectable,
+  Logger,
+  Module,
+  Optional,
+  type DynamicModule,
+  type OnModuleDestroy,
+  type OnModuleInit,
+  type Provider,
+  type Type,
+} from '@nestjs/common';
 import {
   EVENT_BUS,
   EVENT_READ_PORT,
@@ -57,6 +68,12 @@ import { DRIZZLE } from '../../constants/tokens';
 import type { DrizzleClient } from '../../types/drizzle';
 import { DrizzleEventBus } from './event-bus.drizzle-backend';
 import { MemoryEventBus } from './event-bus.memory-backend';
+import type { IEventBus } from './event-bus.protocol';
+import {
+  EventScheduler,
+  scheduledEventsFromRegistry,
+  type RegistrySchedule,
+} from './event-scheduler';
 // #6 — `RedisEventBus` is lazy-loaded only when `backend: 'redis'` is selected.
 // The file is filtered out of the vendor set for non-redis installs (see
 // `backendFileFilter` in src/cli/commands/subsystem.ts); the dynamic-string
@@ -151,6 +168,62 @@ export interface EventsModuleOptions {
    * keeps the bundled bus.
    */
   typedBus?: Type<unknown>;
+  /**
+   * ADR-039 — the consumer's generated `eventRegistry`, threaded so the
+   * `EventScheduler` can read the `schedule:` block + routing metadata of every
+   * scheduled event. Package mode: the generated subsystem barrel passes the
+   * consumer's `eventRegistry` (the bundled one is the package's empty/fixture
+   * registry, which the package can't see the consumer's events through — same
+   * reason `typedBus` is threaded). Omitted ⇒ no scheduler is spawned (vendored
+   * tree reads its own bundled registry only if the barrel passes it; tests
+   * pass a registry directly).
+   *
+   * Structural shape: each value needs `schedule?` + `direction` + `pool`. The
+   * generated `EventMetadata` satisfies it; typing it loosely here avoids a
+   * runtime dependency on the generated types from the module file.
+   */
+  eventRegistry?: Record<
+    string,
+    { schedule?: RegistrySchedule; direction: string | null; pool: string | null }
+  >;
+}
+
+/**
+ * Lifecycle holder for the `EventScheduler` (ADR-039). Registered as a provider
+ * on the drizzle/memory `forRoot` branches; Nest drives `onModuleInit` (after
+ * the bus is constructed) and `onModuleDestroy`. Reads the scheduled-event set
+ * from the threaded `eventRegistry` and starts the materialiser. No-op when
+ * nothing declared `schedule:`, or under the redis backend (no outbox history).
+ */
+@Injectable()
+export class EventSchedulerLifecycle implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(EventSchedulerLifecycle.name);
+  private scheduler: EventScheduler | null = null;
+
+  constructor(
+    @Inject(EVENT_BUS) private readonly bus: IEventBus,
+    @Optional()
+    @Inject(EVENTS_MODULE_OPTIONS)
+    private readonly opts: EventsModuleOptions | null = null,
+  ) {}
+
+  async onModuleInit(): Promise<void> {
+    const registry = this.opts?.eventRegistry;
+    if (!registry) return;
+    if (typeof this.bus.materializeScheduledEvent !== 'function') return; // redis
+    const schedules = scheduledEventsFromRegistry(registry);
+    if (schedules.length === 0) return;
+    this.scheduler = new EventScheduler(this.bus, schedules);
+    await this.scheduler.start();
+    this.logger.log(`EventScheduler wired for ${schedules.length} scheduled event(s).`);
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    if (this.scheduler) {
+      this.scheduler.stop();
+      this.scheduler = null;
+    }
+  }
 }
 
 export interface EventsModuleAsyncOptions {
@@ -317,6 +390,10 @@ export class EventsModule {
         // IEventReadPort on the same instance as EVENT_BUS. The redis
         // backend retains no history and does not provide this token.
         { provide: EVENT_READ_PORT, useExisting: EVENT_BUS },
+        // ADR-039 — the scheduler lifecycle. No-op unless `eventRegistry` was
+        // threaded AND some event declared `schedule:`. Drizzle/memory only
+        // (the redis branch above never reaches here).
+        EventSchedulerLifecycle,
         ...buildTypedBusProviders(multiTenant, options.typedBus),
       ],
       exports: [EVENT_BUS, EVENT_READ_PORT, TYPED_EVENT_BUS, EVENTS_MULTI_TENANT],

package/runtime/subsystems/events/generated/registry.ts

@@ -14,6 +14,7 @@ export interface EventMetadata {
 	destination?: string;
 	version: number;
 	retry: { attempts: number; backoff: 'linear' | 'exponential' };
+	schedule?: { every: string | number; align: boolean; catchUp: boolean; maxCatchUpSlots: number };
 }
 
 export const eventRegistry = {

package/runtime/subsystems/events/index.ts

@@ -3,7 +3,12 @@
  *
  * Import the module in AppModule, inject the bus via EVENT_BUS token.
  */
-export type { DomainEvent, IEventBus, DrizzleTransaction } from './event-bus.protocol';
+export type {
+  DomainEvent,
+  IEventBus,
+  DrizzleTransaction,
+  ScheduledEventSpec,
+} from './event-bus.protocol';
 // Augmentable event registry (ADR-037, package-mode trigger typing). A
 // package-mode consumer's generated events code augments `DomainEventRegistry`
 // via `declare module '@pattern-stack/codegen/runtime/subsystems/events/index'`
@@ -30,9 +35,26 @@ export {
   TYPED_EVENT_BUS,
 } from './events.tokens';
 export { TypedEventBus } from './generated/bus';
-export { MissingTenantIdError } from './events-errors';
-export { EventsModule } from './events.module';
+export { MissingTenantIdError, ScheduleConfigError } from './events-errors';
+export { EventsModule, EventSchedulerLifecycle } from './events.module';
 export type { EventsModuleOptions } from './events.module';
+// ADR-039 — declarative time-based scheduling (time as an event source).
+export {
+  EventScheduler,
+  parseEvery,
+  slotStartFor,
+  nextSlotStart,
+  slotKeyFor,
+  resolveScheduledEvent,
+  scheduledEventsFromRegistry,
+  SCHEDULE_KEY_PREFIX,
+  SCHEDULE_FLOOR_MS,
+} from './event-scheduler';
+export type {
+  ScheduledEvent,
+  RegistrySchedule,
+  EventSchedulerOptions,
+} from './event-scheduler';
 export { MemoryEventBus } from './event-bus.memory-backend';
 export { DrizzleEventBus } from './event-bus.drizzle-backend';
 // #6 — backend-specific implementation classes are NOT re-exported here.

package/dist/chunk-BGULBWKJ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../runtime/subsystems/events/generated/registry.ts"],"sourcesContent":["// AUTO-GENERATED by @pattern-stack/codegen. Do not edit.\n// Run `codegen entity new --all` to refresh.\n\n\nimport type { EventTypeName } from './types';\n\nexport interface EventMetadata {\n\ttype: EventTypeName;\n\ttier: 'domain' | 'audit';\n\tdirection: 'inbound' | 'change' | 'outbound' | null;\n\tpool: 'events_inbound' | 'events_change' | 'events_outbound' | null;\n\taggregate?: string;\n\tsource?: string;\n\tdestination?: string;\n\tversion: number;\n\tretry: { attempts: number; backoff: 'linear' | 'exponential' };\n}\n\nexport const eventRegistry = {\n\t'contact_created': {\n\t\ttype: 'contact_created',\n\t\ttier: 'domain',\n\t\tdirection: 'change',\n\t\tpool: 'events_change',\n\t\taggregate: 'contact',\n\t\tversion: 1,\n\t\tretry: { attempts: 3, backoff: 'exponential' },\n\t},\n\t'contact_marked_champion': {\n\t\ttype: 'contact_marked_champion',\n\t\ttier: 'domain',\n\t\tdirection: 'change',\n\t\tpool: 'events_change',\n\t\taggregate: 'contact',\n\t\tversion: 1,\n\t\tretry: { attempts: 3, backoff: 'exponential' },\n\t},\n\t'contact_merged': {\n\t\ttype: 'contact_merged',\n\t\ttier: 'domain',\n\t\tdirection: 'change',\n\t\tpool: 'events_change',\n\t\taggregate: 'contact',\n\t\tversion: 1,\n\t\tretry: { attempts: 3, backoff: 'exponential' },\n\t},\n\t'crm_sync_started': {\n\t\ttype: 'crm_sync_started',\n\t\ttier: 'audit',\n\t\tdirection: null,\n\t\tpool: null,\n\t\tversion: 1,\n\t\tretry: { attempts: 3, backoff: 'exponential' },\n\t},\n\t'deal_created': {\n\t\ttype: 'deal_created',\n\t\ttier: 'domain',\n\t\tdirection: 'change',\n\t\tpool: 'events_change',\n\t\taggregate: 'deal',\n\t\tversion: 1,\n\t\tretry: { attempts: 3, backoff: 'exponential' },\n\t},\n\t'deal_stage_changed': {\n\t\ttype: 'deal_stage_changed',\n\t\ttier: 'domain',\n\t\tdirection: 'change',\n\t\tpool: 'events_change',\n\t\taggregate: 'deal',\n\t\tversion: 1,\n\t\tretry: { attempts: 3, backoff: 'exponential' },\n\t},\n\t'stripe_payment_received': {\n\t\ttype: 'stripe_payment_received',\n\t\ttier: 'domain',\n\t\tdirection: 'inbound',\n\t\tpool: 'events_inbound',\n\t\tsource: 'stripe',\n\t\tversion: 1,\n\t\tretry: { attempts: 5, backoff: 'exponential' },\n\t},\n\t'webhook_outbound_contact_sync': {\n\t\ttype: 'webhook_outbound_contact_sync',\n\t\ttier: 'domain',\n\t\tdirection: 'outbound',\n\t\tpool: 'events_outbound',\n\t\taggregate: 'contact',\n\t\tdestination: 'crm',\n\t\tversion: 1,\n\t\tretry: { attempts: 3, backoff: 'exponential' },\n\t},\n} as const satisfies Record<EventTypeName, EventMetadata>;\n\nexport function getEventMetadata<T extends EventTypeName>(type: T): EventMetadata {\n\tconst meta = eventRegistry[type];\n\tif (!meta) {\n\t\tthrow new Error(`No registry entry for event type '${String(type)}' — declare events under events/*.yaml and re-run \\`codegen entity new --all\\`.`);\n\t}\n\treturn meta;\n}\n"],"mappings":";AAkBO,IAAM,gBAAgB;AAAA,EAC5B,mBAAmB;AAAA,IAClB,MAAM;AAAA,IACN,MAAM;AAAA,IACN,WAAW;AAAA,IACX,MAAM;AAAA,IACN,WAAW;AAAA,IACX,SAAS;AAAA,IACT,OAAO,EAAE,UAAU,GAAG,SAAS,cAAc;AAAA,EAC9C;AAAA,EACA,2BAA2B;AAAA,IAC1B,MAAM;AAAA,IACN,MAAM;AAAA,IACN,WAAW;AAAA,IACX,MAAM;AAAA,IACN,WAAW;AAAA,IACX,SAAS;AAAA,IACT,OAAO,EAAE,UAAU,GAAG,SAAS,cAAc;AAAA,EAC9C;AAAA,EACA,kBAAkB;AAAA,IACjB,MAAM;AAAA,IACN,MAAM;AAAA,IACN,WAAW;AAAA,IACX,MAAM;AAAA,IACN,WAAW;AAAA,IACX,SAAS;AAAA,IACT,OAAO,EAAE,UAAU,GAAG,SAAS,cAAc;AAAA,EAC9C;AAAA,EACA,oBAAoB;AAAA,IACnB,MAAM;AAAA,IACN,MAAM;AAAA,IACN,WAAW;AAAA,IACX,MAAM;AAAA,IACN,SAAS;AAAA,IACT,OAAO,EAAE,UAAU,GAAG,SAAS,cAAc;AAAA,EAC9C;AAAA,EACA,gBAAgB;AAAA,IACf,MAAM;AAAA,IACN,MAAM;AAAA,IACN,WAAW;AAAA,IACX,MAAM;AAAA,IACN,WAAW;AAAA,IACX,SAAS;AAAA,IACT,OAAO,EAAE,UAAU,GAAG,SAAS,cAAc;AAAA,EAC9C;AAAA,EACA,sBAAsB;AAAA,IACrB,MAAM;AAAA,IACN,MAAM;AAAA,IACN,WAAW;AAAA,IACX,MAAM;AAAA,IACN,WAAW;AAAA,IACX,SAAS;AAAA,IACT,OAAO,EAAE,UAAU,GAAG,SAAS,cAAc;AAAA,EAC9C;AAAA,EACA,2BAA2B;AAAA,IAC1B,MAAM;AAAA,IACN,MAAM;AAAA,IACN,WAAW;AAAA,IACX,MAAM;AAAA,IACN,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,OAAO,EAAE,UAAU,GAAG,SAAS,cAAc;AAAA,EAC9C;AAAA,EACA,iCAAiC;AAAA,IAChC,MAAM;AAAA,IACN,MAAM;AAAA,IACN,WAAW;AAAA,IACX,MAAM;AAAA,IACN,WAAW;AAAA,IACX,aAAa;AAAA,IACb,SAAS;AAAA,IACT,OAAO,EAAE,UAAU,GAAG,SAAS,cAAc;AAAA,EAC9C;AACD;AAEO,SAAS,iBAA0C,MAAwB;AACjF,QAAM,OAAO,cAAc,IAAI;AAC/B,MAAI,CAAC,MAAM;AACV,UAAM,IAAI,MAAM,qCAAqC,OAAO,IAAI,CAAC,sFAAiF;AAAA,EACnJ;AACA,SAAO;AACR;","names":[]}