archstone 1.3.0-rc.2 → 1.3.0-rc.4

package/README.md

@@ -174,13 +174,25 @@ tags.getRemovedItems() // → [existingTag]
 ### Domain Events — decouple side effects
 
 ```ts
-import { DomainEvents } from 'archstone/domain/enterprise'
+import type { EventHandler } from 'archstone/core'
+import { DomainEvents } from 'archstone/core'
 
-// Register handlers anywhere in your infrastructure layer
-DomainEvents.register(
-  (event) => sendWelcomeEmail(event as UserCreatedEvent),
-  UserCreatedEvent.name,
-)
+class OnUserCreated implements EventHandler<UserCreatedEvent> {
+  constructor(private readonly mailer: Mailer) {
+    this.setupSubscriptions()
+  }
+
+  setupSubscriptions(): void {
+    DomainEvents.register(this.handle.bind(this), UserCreatedEvent.name)
+  }
+
+  async handle(event: UserCreatedEvent): Promise<void> {
+    await this.mailer.send(event.user.email.value)
+  }
+}
+
+// Instantiate in infrastructure — handler self-registers via constructor
+new OnUserCreated(mailer)
 
 // Dispatch after persistence — events stay inside the aggregate until then
 await userRepository.create(user)
@@ -212,9 +224,9 @@ export interface AuditRepository extends Creatable<AuditLog> {}
 | Import | Contents |
 |---|---|
 | `archstone` | Everything |
-| `archstone/core` | `Either`, `ValueObject`, `UniqueEntityId`, `WatchedList`, `Optional` |
+| `archstone/core` | `Either`, `ValueObject`, `UniqueEntityId`, `WatchedList`, `Optional`, `EventHandler` |
 | `archstone/domain` | All domain exports |
-| `archstone/domain/enterprise` | `Entity`, `AggregateRoot`, `DomainEvent`, `DomainEvents`, `EventHandler` |
+| `archstone/domain/enterprise` | `Entity`, `AggregateRoot`, `DomainEvent`, `DomainEvents` |
 | `archstone/domain/application` | `UseCase`, `UseCaseError`, repository contracts |
 
 All sub-paths share type declarations via a common chunk — mixing imports from multiple sub-paths is fully type-safe with no duplicate declaration conflicts.

package/dist/core/index.d.ts

@@ -1,2 +1,2 @@
-import { DomainEvent, DomainEvents, Either, EventHandler, Optional, UniqueEntityId, ValueObject, WatchedList, left, right } from "../shared/chunk-rgs8z093.js";
+import { DomainEvent, DomainEvents, Either, EventHandler1 as EventHandler, Optional, UniqueEntityId, ValueObject, WatchedList, left, right } from "../shared/chunk-z9br464b.js";
 export { right, left, WatchedList, ValueObject, UniqueEntityId, Optional, EventHandler, Either, DomainEvents, DomainEvent };

package/dist/domain/application/index.d.ts

@@ -1,2 +1,2 @@
-import { Creatable, Deletable, Findable, Repository, Saveable, UseCase, UseCaseError } from "../../shared/chunk-rgs8z093.js";
+import { Creatable, Deletable, Findable, Repository, Saveable, UseCase, UseCaseError } from "../../shared/chunk-z9br464b.js";
 export { UseCaseError, UseCase, Saveable, Repository, Findable, Deletable, Creatable };

package/dist/domain/enterprise/index.d.ts

@@ -1,2 +1,2 @@
-import { AggregateRoot, DomainEvent, DomainEvents, Entity, EventHandler } from "../../shared/chunk-rgs8z093.js";
+import { AggregateRoot, DomainEvent, DomainEvents, Entity, EventHandler } from "../../shared/chunk-z9br464b.js";
 export { EventHandler, Entity, DomainEvents, DomainEvent, AggregateRoot };

package/dist/domain/enterprise/index.js

@@ -1,2 +1,2 @@
 // @bun
-import{a as b,b as c}from"../../shared/chunk-s2r7zghq.js";import{e as a}from"../../shared/chunk-8hx7pxm3.js";export{b as Entity,a as DomainEvents,c as AggregateRoot};
+import{a as b,b as c}from"../../shared/chunk-k39ksk62.js";import{e as a}from"../../shared/chunk-8hx7pxm3.js";export{b as Entity,a as DomainEvents,c as AggregateRoot};

package/dist/domain/index.d.ts

@@ -1,2 +1,2 @@
-import { AggregateRoot, Creatable, Deletable, DomainEvent, DomainEvents, Entity, EventHandler, Findable, Repository, Saveable, UseCase, UseCaseError } from "../shared/chunk-rgs8z093.js";
+import { AggregateRoot, Creatable, Deletable, DomainEvent, DomainEvents, Entity, EventHandler, Findable, Repository, Saveable, UseCase, UseCaseError } from "../shared/chunk-z9br464b.js";
 export { UseCaseError, UseCase, Saveable, Repository, Findable, EventHandler, Entity, DomainEvents, DomainEvent, Deletable, Creatable, AggregateRoot };

package/dist/domain/index.js

@@ -1,2 +1,2 @@
 // @bun
-import"../shared/chunk-x296z7h1.js";import"../shared/chunk-wsjyhnpq.js";import{a as b,b as c}from"../shared/chunk-s2r7zghq.js";import{e as a}from"../shared/chunk-8hx7pxm3.js";export{b as Entity,a as DomainEvents,c as AggregateRoot};
+import"../shared/chunk-x296z7h1.js";import"../shared/chunk-wsjyhnpq.js";import{a as b,b as c}from"../shared/chunk-k39ksk62.js";import{e as a}from"../shared/chunk-8hx7pxm3.js";export{b as Entity,a as DomainEvents,c as AggregateRoot};

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { AggregateRoot, Creatable, Deletable, DomainEvent, DomainEvents, Either, Entity, EventHandler, Findable, Optional, Repository, Saveable, UniqueEntityId, UseCase, UseCaseError, ValueObject, WatchedList, left, right } from "./shared/chunk-rgs8z093.js";
-export { right, left, WatchedList, ValueObject, UseCaseError, UseCase, UniqueEntityId, Saveable, Repository, Optional, Findable, EventHandler, Entity, Either, DomainEvents, DomainEvent, Deletable, Creatable, AggregateRoot };
+import { AggregateRoot, Creatable, Deletable, DomainEvent, DomainEvents, Either, Entity, Findable, Optional, Repository, Saveable, UniqueEntityId, UseCase, UseCaseError, ValueObject, WatchedList, left, right } from "./shared/chunk-z9br464b.js";
+export { right, left, WatchedList, ValueObject, UseCaseError, UseCase, UniqueEntityId, Saveable, Repository, Optional, Findable, Entity, Either, DomainEvents, DomainEvent, Deletable, Creatable, AggregateRoot };

package/dist/index.js

@@ -1,2 +1,2 @@
 // @bun
-import"./shared/chunk-x296z7h1.js";import"./shared/chunk-wsjyhnpq.js";import{a as b,b as c}from"./shared/chunk-s2r7zghq.js";import{c as f,d as m,e as p,f as t,g as x,h as a}from"./shared/chunk-8hx7pxm3.js";export{m as right,f as left,a as WatchedList,x as ValueObject,t as UniqueEntityId,b as Entity,p as DomainEvents,c as AggregateRoot};
+import"./shared/chunk-x296z7h1.js";import"./shared/chunk-wsjyhnpq.js";import{a as b,b as c}from"./shared/chunk-k39ksk62.js";import{c as f,d as m,e as p,f as t,g as x,h as a}from"./shared/chunk-8hx7pxm3.js";export{m as right,f as left,a as WatchedList,x as ValueObject,t as UniqueEntityId,b as Entity,p as DomainEvents,c as AggregateRoot};

package/dist/shared/chunk-k39ksk62.js

@@ -0,0 +1,2 @@
+// @bun
+import{e as j,f as k}from"./chunk-8hx7pxm3.js";class R{_id;props;get id(){return this._id}constructor(A,B){this._id=B??new k,this.props=A}equals(A){if(A===this)return!0;return A.id.equals(this._id)}}class z extends R{_domainEvents=new Set;get domainEvents(){return Array.from(this._domainEvents)}addDomainEvent(A){this._domainEvents.add(A),j.markAggregateForDispatch(this)}clearEvents(){this._domainEvents.clear()}}export{R as a,z as b};

package/dist/shared/{chunk-rgs8z093.d.ts → chunk-z9br464b.d.ts}

@@ -305,9 +305,22 @@ declare abstract class AggregateRoot<Props> extends Entity<Props> {
 	clearEvents(): void;
 }
 /**
+* @deprecated use `EventHandler` from `archstone/core` instead.
+* The new version supports generic typing via `EventHandler<T>`.
+*/
+interface EventHandler {
+	setupSubscriptions(): void;
+}
+/**
 * Callback function invoked when a domain event is dispatched.
+*
+* The bivariant method signature allows handlers typed to a specific
+* `DomainEvent` subtype to be registered — TypeScript enforces strict
+* contravariance on function types but not on method signatures.
 */
-type DomainEventCallback = (event: DomainEvent) => void;
+type DomainEventCallback = {
+	bivarianceHack(event: DomainEvent): Promise<void>;
+}["bivarianceHack"];
 /**
 * Central registry and dispatcher for domain events.
 *
@@ -376,39 +389,54 @@ declare class DomainEventsImplementation {
 */
 declare const DomainEvents: DomainEventsImplementation;
 /**
-* Base contract for all event handlers.
+* Base contract for all domain event handlers.
 *
 * An event handler is responsible for subscribing to domain events
-* and executing side effects in response — such as sending emails,
-* updating read models, or triggering external integrations.
+* and executing side effects in response — such as persisting records,
+* broadcasting WebSocket messages, sending emails, or triggering
+* external integrations.
+*
+* Implement {@link setupSubscriptions} to register callbacks in the
+* {@link DomainEvents} registry, and {@link handle} to define the
+* reaction logic for the subscribed event.
 *
-* All handlers must implement {@link setupSubscriptions} to register
-* their callbacks in the {@link DomainEvents} registry.
+* @typeParam T - The specific {@link DomainEvent} this handler reacts to.
 *
 * @example
 * ```ts
-* class OnUserCreated implements EventHandler {
-*   constructor(private readonly mailer: Mailer) {}
+* class OnUserCreated implements EventHandler<UserCreatedEvent> {
+*   constructor(private readonly mailer: Mailer) {
+*     this.setupSubscriptions()
+*   }
 *
 *   setupSubscriptions(): void {
 *     DomainEvents.register(
-*       (event) => this.sendWelcomeEmail(event as UserCreatedEvent),
+*       this.handle.bind(this),
 *       UserCreatedEvent.name,
 *     )
 *   }
 *
-*   private async sendWelcomeEmail(event: UserCreatedEvent): Promise<void> {
+*   async handle(event: UserCreatedEvent): Promise<void> {
 *     await this.mailer.send(event.user.email)
 *   }
 * }
 * ```
 */
-interface EventHandler {
+interface EventHandler2<T extends DomainEvent> {
 	/**
 	* Registers all event subscriptions for this handler.
-	* Should be called once during application bootstrap.
+	*
+	* Should be called once during instantiation — typically
+	* in the constructor — to ensure the handler is active
+	* before any events are dispatched.
 	*/
 	setupSubscriptions(): void;
+	/**
+	* Executes the handler logic in response to a dispatched event.
+	*
+	* @param event - The domain event instance that was dispatched.
+	*/
+	handle(event: T): Promise<void>;
 }
 /**
 * Make some property optional on type
@@ -634,4 +662,4 @@ interface UseCase<
 > {
 	execute(input: Input): Promise<Output>;
 }
-export { Either, left, right, DomainEvent, Creatable, Deletable, Findable, Saveable, Repository, UseCaseError, UseCase, Entity, AggregateRoot, DomainEvents, EventHandler, Optional, UniqueEntityId, ValueObject, WatchedList };
+export { Either, left, right, DomainEvent, Creatable, Deletable, Findable, Saveable, Repository, UseCaseError, UseCase, Entity, AggregateRoot, EventHandler, DomainEvents, EventHandler2 as EventHandler1, Optional, UniqueEntityId, ValueObject, WatchedList };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "archstone",
   "description": "TypeScript architecture foundation for backend services based on Domain-Driven Design and Clean Architecture",
-  "version": "1.3.0-rc.2",
+  "version": "1.3.0-rc.4",
   "type": "module",
   "private": false,
   "files": [

package/skills/use-archstone/references/domain-events.md

@@ -4,8 +4,8 @@
 
 - Raise events inside the aggregate via `this.addDomainEvent()`
 - Dispatch **after** successful persistence — never before
-- Define handlers as classes implementing `EventHandler` with `setupSubscriptions(): void`
-- Register handlers in the infrastructure composition root before the first request
+- Define handlers as classes implementing `EventHandler<T>` from `archstone/core` with `setupSubscriptions()` and `handle(event: T)`
+- Call `setupSubscriptions()` in the constructor — just instantiate the handler in the composition root
 - Dispatch via `DomainEvents.dispatchEventsForAggregate(aggregate.id)` — argument is `UniqueEntityId`
 - `clearEvents()` is called internally by `dispatchEventsForAggregate` — do not call manually
 - Test isolation: call `DomainEvents.clearHandlers()` and `DomainEvents.clearMarkedAggregates()` in `beforeEach`
@@ -28,20 +28,22 @@ class User extends AggregateRoot<UserProps> {
 ## Defining a Handler
 
 ```ts
-import type { EventHandler } from 'archstone/domain/enterprise'
-import { DomainEvents } from 'archstone/domain/enterprise'
+import type { EventHandler } from 'archstone/core'
+import { DomainEvents } from 'archstone/core'
 
-class OnUserCreated implements EventHandler {
-  constructor(private readonly mailer: Mailer) {}
+class OnUserCreated implements EventHandler<UserCreatedEvent> {
+  constructor(private readonly mailer: Mailer) {
+    this.setupSubscriptions()
+  }
 
   setupSubscriptions(): void {
     DomainEvents.register(
-      (event) => this.handle(event as UserCreatedEvent),
+      this.handle.bind(this),
       UserCreatedEvent.name,
     )
   }
 
-  private async handle(event: UserCreatedEvent): Promise<void> {
+  async handle(event: UserCreatedEvent): Promise<void> {
     await this.mailer.send(event.user.email.value)
   }
 }
@@ -59,8 +61,8 @@ async create(user: User): Promise<void> {
 ## Composition Root Registration
 
 ```ts
-// Called once at app startup — in infrastructure, never in domain
-new OnUserCreated(mailer).setupSubscriptions()
+// setupSubscriptions() is called in the constructor — just instantiate
+new OnUserCreated(mailer)
 ```
 
 ## Common Mistakes

package/dist/shared/chunk-s2r7zghq.js

@@ -1,2 +0,0 @@
-// @bun
-import{e as D,f as H}from"./chunk-8hx7pxm3.js";class A{_id;props;get id(){return this._id}constructor(x,f){this._id=f??new H,this.props=x}equals(x){if(x===this)return!0;return x.id.equals(this._id)}}class R extends A{_domainEvents=new Set;get domainEvents(){return Array.from(this._domainEvents)}addDomainEvent(x){this._domainEvents.add(x),D.markAggregateForDispatch(this)}clearEvents(){this._domainEvents.clear()}}export{A as a,R as b};