archstone 1.3.0 → 1.3.1

package/README.md

@@ -224,9 +224,9 @@ export interface AuditRepository extends Creatable<AuditLog> {}
 | Import | Contents |
 |---|---|
 | `archstone` | Everything |
-| `archstone/core` | `Either`, `ValueObject`, `UniqueEntityId`, `WatchedList`, `Optional`, `EventHandler` |
+| `archstone/core` | `Either`, `ValueObject`, `UniqueEntityId`, `WatchedList`, `Optional`, `DomainEvent`, `DomainEvents`, `EventHandler` |
 | `archstone/domain` | All domain exports |
-| `archstone/domain/enterprise` | `Entity`, `AggregateRoot`, `DomainEvent`, `DomainEvents` |
+| `archstone/domain/enterprise` | `Entity`, `AggregateRoot` |
 | `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.
@@ -242,18 +242,18 @@ src/
 │   ├── value-object.ts      # Value equality base class
 │   ├── unique-entity-id.ts  # UUID v7 identity wrapper
 │   ├── watched-list.ts      # Change-tracked collection
+│   ├── events/
+│   │   ├── domain-event.ts  # Marker interface for all domain events
+│   │   ├── domain-events.ts # Central registry and dispatcher (singleton)
+│   │   └── event-handler.ts # Generic handler interface EventHandler<T>
 │   └── types/
 │       └── optional.ts      # Optional<T, K> helper type
 │
 └── domain/
     ├── enterprise/          # Pure domain model — zero framework dependencies
-    │   ├── entities/
-    │   │   ├── entity.ts
-    │   │   └── aggregate-root.ts
-    │   └── events/
-    │       ├── domain-event.ts
-    │       ├── domain-events.ts
-    │       └── event-handler.ts
+    │   └── entities/
+    │       ├── entity.ts
+    │       └── aggregate-root.ts
     │
     └── application/         # Orchestration — use cases & repository contracts
         ├── use-cases/
@@ -269,6 +269,73 @@ src/
 
 ---
 
+## Technology Stack
+
+| | |
+|---|---|
+| **Language** | TypeScript 5+ |
+| **Runtime / Package Manager** | [Bun](https://bun.sh) (required) |
+| **Test Framework** | `bun:test` (built-in) |
+| **Build Tool** | [bunup](https://github.com/nicepkg/bunup) |
+| **Linter / Formatter** | [Biome](https://biomejs.dev) via [Ultracite](https://ultracite.dev) |
+| **Dependencies** | None (zero runtime dependencies) |
+
+---
+
+## Development Workflow
+
+Requirements: **Bun >= 1.0**
+
+```bash
+bun install          # install dev dependencies
+bun test             # run tests
+bun run build        # compile to dist/
+bun x ultracite fix  # lint + format
+```
+
+Branch naming: `feat/<name>`, `fix/<name>`, `docs/<name>`, `chore/<name>`
+
+Every commit must pass `bun test` and `bun x ultracite fix` before pushing.
+
+---
+
+## Coding Standards
+
+- **Error handling:** never throw inside use cases — always return `left(error)` with `Either`
+- **Imports:** always import from a layer's index (`archstone/core`, `archstone/domain/enterprise`), never from deep paths
+- **Layer boundaries:** inner layers never import outer ones — `core` has zero domain knowledge, `enterprise` never imports `application`
+- **Factories:** always provide a static `create()` factory on entities and value objects — never expose constructors directly
+- **Style:** no semicolons, 2-space indent, double quotes (enforced by Biome via Ultracite)
+- **Commits:** [Conventional Commits](https://www.conventionalcommits.org/) — `feat`, `fix`, `chore`, `docs`, `refactor`, `test`
+
+---
+
+## Testing
+
+Framework: `bun:test`. Test files are `*.spec.ts` co-located with the source they test.
+
+```ts
+import { test, expect } from "bun:test"
+
+test("example", () => {
+  expect(1).toBe(1)
+})
+```
+
+Use **in-memory repository implementations** for use case tests — never couple tests to a real database. Isolate domain event state between tests:
+
+```ts
+import { DomainEvents } from "archstone/core"
+import { beforeEach } from "bun:test"
+
+beforeEach(() => {
+  DomainEvents.clearHandlers()
+  DomainEvents.clearMarkedAggregates()
+})
+```
+
+---
+
 ## Agent Skills — new in v1.1.0
 
 Archstone ships with a built-in skill for AI coding agents. Once installed, your agent understands every DDD convention, layer boundary, and usage pattern — without you ever having to explain them.
@@ -297,7 +364,7 @@ cp -r node_modules/archstone/skills/use-archstone .claude/skills/
 
 <div align="center">
 
-**Built with care for the TypeScript community.**
+**Built with ❤️ for the TypeScript community.**
 
 [Contributing](./CONTRIBUTING.md) · [Code of Conduct](./CODE_OF_CONDUCT.md) · [MIT License](./LICENSE)
 

package/dist/core/index.d.ts

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

package/dist/core/index.js

@@ -1,2 +1,2 @@
 // @bun
-import{c as a,d as b,e as c,f as d,g as e,h as f}from"../shared/chunk-8hx7pxm3.js";export{b as right,a as left,f as WatchedList,e as ValueObject,d as UniqueEntityId,c as DomainEvents};
+import{c as a,d as b,e as c,f as d,g as e,h as f}from"../shared/chunk-k4yvnajk.js";export{b as right,a as left,f as WatchedList,e as ValueObject,d as UniqueEntityId,c as DomainEvents};

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

@@ -1,2 +1,2 @@
-import { Creatable, Deletable, Findable, Repository, Saveable, UseCase, UseCaseError } from "../../shared/chunk-z9br464b.js";
+import { Creatable, Deletable, Findable, Repository, Saveable, UseCase, UseCaseError } from "../../shared/chunk-ghvxv2w6.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-z9br464b.js";
+import { AggregateRoot, DomainEvent, DomainEvents, Entity, EventHandler } from "../../shared/chunk-ghvxv2w6.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-k39ksk62.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-ph10w7xb.js";import{e as a}from"../../shared/chunk-k4yvnajk.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-z9br464b.js";
+import { AggregateRoot, Creatable, Deletable, DomainEvent, DomainEvents, Entity, EventHandler, Findable, Repository, Saveable, UseCase, UseCaseError } from "../shared/chunk-ghvxv2w6.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-k39ksk62.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-ph10w7xb.js";import{e as a}from"../shared/chunk-k4yvnajk.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, Findable, Optional, Repository, Saveable, UniqueEntityId, UseCase, UseCaseError, ValueObject, WatchedList, left, right } from "./shared/chunk-z9br464b.js";
+import { AggregateRoot, Creatable, Deletable, DomainEvent, DomainEvents, Either, Entity, Findable, Optional, Repository, Saveable, UniqueEntityId, UseCase, UseCaseError, ValueObject, WatchedList, left, right } from "./shared/chunk-ghvxv2w6.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-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};
+import"./shared/chunk-x296z7h1.js";import"./shared/chunk-wsjyhnpq.js";import{a as b,b as c}from"./shared/chunk-ph10w7xb.js";import{c as f,d as m,e as p,f as t,g as x,h as a}from"./shared/chunk-k4yvnajk.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-z9br464b.d.ts → chunk-ghvxv2w6.d.ts}

@@ -346,6 +346,15 @@ declare class DomainEventsImplementation {
 	private readonly handlersMap;
 	private readonly markedAggregates;
 	/**
+	* Controls whether event dispatching is active.
+	*
+	* Set to `false` in tests that construct aggregates but do not want
+	* side-effects to run, without having to clear and re-register handlers.
+	*
+	* @default true
+	*/
+	shouldRun: boolean;
+	/**
 	* Marks an aggregate root to have its events dispatched.
 	* Called automatically by {@link AggregateRoot.addDomainEvent}.
 	*

package/dist/shared/chunk-k4yvnajk.js

@@ -0,0 +1,2 @@
+// @bun
+class H{value;constructor(x){this.value=x}isRight(){return!1}isLeft(){return!0}}class V{value;constructor(x){this.value=x}isRight(){return!0}isLeft(){return!1}}var B=(x)=>new H(x),F=(x)=>new V(x);class W{handlersMap=new Map;markedAggregates=new Set;shouldRun=!0;markAggregateForDispatch(x){if(!this.findMarkedAggregateByID(x.id))this.markedAggregates.add(x)}dispatchEventsForAggregate(x){let E=this.findMarkedAggregateByID(x);if(E)this.dispatchAggregateEvents(E),E.clearEvents(),this.removeAggregateFromMarkedDispatchList(E)}register(x,E){if(!this.handlersMap.has(E))this.handlersMap.set(E,[]);this.handlersMap.get(E)?.push(x)}clearHandlers(){this.handlersMap.clear()}clearMarkedAggregates(){this.markedAggregates.clear()}dispatchAggregateEvents(x){for(let E of x.domainEvents)this.dispatch(E)}removeAggregateFromMarkedDispatchList(x){this.markedAggregates.delete(x)}findMarkedAggregateByID(x){return[...this.markedAggregates].find((E)=>E.id.equals(x))}dispatch(x){if(!this.shouldRun)return;let E=this.handlersMap.get(x.constructor.name)??[];for(let O of E)O(x)}}var G=new W;var{randomUUIDv7:J}=globalThis.Bun;class f{value;constructor(x){this.value=x??J()}toValue(){return this.value}toString(){return this.value}equals(x){return x.toValue()===this.value}}class z{props;constructor(x){this.props=x}equals(x){return JSON.stringify(this.props)===JSON.stringify(x.props)}}class A{currentItems;initial;new;removed;constructor(x){this.currentItems=x??[],this.initial=x??[],this.new=[],this.removed=[]}getItems(){return this.currentItems}getNewItems(){return this.new}getRemovedItems(){return this.removed}exists(x){return this.isCurrentItem(x)}add(x){if(this.isRemovedItem(x))this.removeFromRemoved(x);if(!(this.isNewItem(x)||this.wasAddedInitially(x)))this.new.push(x);if(!this.isCurrentItem(x))this.currentItems.push(x)}remove(x){if(this.removeFromCurrent(x),this.isNewItem(x)){this.removeFromNew(x);return}if(!this.isRemovedItem(x))this.removed.push(x)}update(x){this.new=x.filter((E)=>!this.getItems().some((O)=>this.compareItems(E,O))),this.removed=this.getItems().filter((E)=>!x.some((O)=>this.compareItems(E,O))),this.currentItems=x}isCurrentItem(x){return this.currentItems.some((E)=>this.compareItems(x,E))}isNewItem(x){return this.new.some((E)=>this.compareItems(x,E))}isRemovedItem(x){return this.removed.some((E)=>this.compareItems(x,E))}removeFromNew(x){this.new=this.new.filter((E)=>!this.compareItems(E,x))}removeFromCurrent(x){this.currentItems=this.currentItems.filter((E)=>!this.compareItems(x,E))}removeFromRemoved(x){this.removed=this.removed.filter((E)=>!this.compareItems(x,E))}wasAddedInitially(x){return this.initial.some((E)=>this.compareItems(x,E))}}export{B as c,F as d,G as e,f,z as g,A as h};

package/dist/shared/{chunk-k39ksk62.js → chunk-ph10w7xb.js}

@@ -1,2 +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};
+import{e as j,f as k}from"./chunk-k4yvnajk.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/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",
+  "version": "1.3.1",
   "type": "module",
   "private": false,
   "files": [

package/dist/shared/chunk-8hx7pxm3.js

@@ -1,2 +0,0 @@
-// @bun
-class H{value;constructor(x){this.value=x}isRight(){return!1}isLeft(){return!0}}class V{value;constructor(x){this.value=x}isRight(){return!0}isLeft(){return!1}}var B=(x)=>new H(x),F=(x)=>new V(x);class W{handlersMap=new Map;markedAggregates=new Set;markAggregateForDispatch(x){if(!this.findMarkedAggregateByID(x.id))this.markedAggregates.add(x)}dispatchEventsForAggregate(x){let E=this.findMarkedAggregateByID(x);if(E)this.dispatchAggregateEvents(E),E.clearEvents(),this.removeAggregateFromMarkedDispatchList(E)}register(x,E){if(!this.handlersMap.has(E))this.handlersMap.set(E,[]);this.handlersMap.get(E)?.push(x)}clearHandlers(){this.handlersMap.clear()}clearMarkedAggregates(){this.markedAggregates.clear()}dispatchAggregateEvents(x){for(let E of x.domainEvents)this.dispatch(E)}removeAggregateFromMarkedDispatchList(x){this.markedAggregates.delete(x)}findMarkedAggregateByID(x){return[...this.markedAggregates].find((E)=>E.id.equals(x))}dispatch(x){let E=this.handlersMap.get(x.constructor.name)??[];for(let O of E)O(x)}}var G=new W;var{randomUUIDv7:J}=globalThis.Bun;class f{value;constructor(x){this.value=x??J()}toValue(){return this.value}toString(){return this.value}equals(x){return x.toValue()===this.value}}class z{props;constructor(x){this.props=x}equals(x){return JSON.stringify(this.props)===JSON.stringify(x.props)}}class A{currentItems;initial;new;removed;constructor(x){this.currentItems=x??[],this.initial=x??[],this.new=[],this.removed=[]}getItems(){return this.currentItems}getNewItems(){return this.new}getRemovedItems(){return this.removed}exists(x){return this.isCurrentItem(x)}add(x){if(this.isRemovedItem(x))this.removeFromRemoved(x);if(!(this.isNewItem(x)||this.wasAddedInitially(x)))this.new.push(x);if(!this.isCurrentItem(x))this.currentItems.push(x)}remove(x){if(this.removeFromCurrent(x),this.isNewItem(x)){this.removeFromNew(x);return}if(!this.isRemovedItem(x))this.removed.push(x)}update(x){this.new=x.filter((E)=>!this.getItems().some((O)=>this.compareItems(E,O))),this.removed=this.getItems().filter((E)=>!x.some((O)=>this.compareItems(E,O))),this.currentItems=x}isCurrentItem(x){return this.currentItems.some((E)=>this.compareItems(x,E))}isNewItem(x){return this.new.some((E)=>this.compareItems(x,E))}isRemovedItem(x){return this.removed.some((E)=>this.compareItems(x,E))}removeFromNew(x){this.new=this.new.filter((E)=>!this.compareItems(E,x))}removeFromCurrent(x){this.currentItems=this.currentItems.filter((E)=>!this.compareItems(x,E))}removeFromRemoved(x){this.removed=this.removed.filter((E)=>!this.compareItems(x,E))}wasAddedInitially(x){return this.initial.some((E)=>this.compareItems(x,E))}}export{B as c,F as d,G as e,f,z as g,A as h};