archstone 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 João Henrique Benatti Coimbra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,10 +1,32 @@
 # archstone
 
-A TypeScript-first architecture foundation for backend services, built around Domain-Driven Design (DDD) and Clean Architecture principles.
+[![npm version](https://img.shields.io/npm/v/archstone?style=flat-square)](https://www.npmjs.com/package/archstone)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Bun](https://img.shields.io/badge/Bun-runtime-black?style=flat-square&logo=bun)](https://bun.sh)
+
+> TypeScript architecture foundation for backend services based on Domain-Driven Design (DDD) and Clean Architecture.
 
 Archstone provides the core building blocks — entities, value objects, aggregates, domain events, use cases, and repository contracts — so you can focus on your domain logic instead of re-implementing the same structural patterns across every project.
 
-## Layers
+## Installation
+
+```bash
+bun add archstone
+# or
+npm install archstone
+```
+
+## Packages
+
+| Import path | Contents |
+|---|---|
+| `archstone/core` | `Either`, `ValueObject`, `UniqueEntityId`, `WatchedList`, `Optional` |
+| `archstone/domain` | All domain exports |
+| `archstone/domain/enterprise` | `Entity`, `AggregateRoot`, `DomainEvent`, `DomainEvents`, `EventHandler` |
+| `archstone/domain/application` | `UseCase`, `UseCaseError`, repository contracts |
+
+## Architecture
 
 ```
 src/
@@ -45,7 +67,7 @@ src/
 Use cases never throw. They return an `Either<Error, Value>` — left for failure, right for success.
 
 ```ts
-import { Either, left, right } from "@/core/either"
+import { Either, left, right } from "archstone/core"
 
 type Result = Either<UserNotFoundError, User>
 
@@ -65,9 +87,8 @@ else console.log(result.value)                    // User
 Entities are defined by identity. Aggregates extend that with domain event support.
 
 ```ts
-import { AggregateRoot } from "@/domain/enterprise/entities/aggregate-root"
-import { UniqueEntityId } from "@/core/unique-entity-id"
-import { Optional } from "@/core/types/optional"
+import { AggregateRoot } from "archstone/domain/enterprise"
+import { UniqueEntityId, Optional } from "archstone/core"
 
 interface OrderProps {
   customerId: UniqueEntityId
@@ -94,7 +115,7 @@ class Order extends AggregateRoot<OrderProps> {
 Value objects are equal by their properties, not by reference.
 
 ```ts
-import { ValueObject } from "@/core/value-object"
+import { ValueObject } from "archstone/core"
 
 interface EmailProps { value: string }
 
@@ -113,6 +134,8 @@ class Email extends ValueObject<EmailProps> {
 Track additions and removals in a collection without rewriting the whole thing on save.
 
 ```ts
+import { WatchedList } from "archstone/core"
+
 class TagList extends WatchedList<Tag> {
   compareItems(a: Tag, b: Tag) { return a.id.equals(b.id) }
 }
@@ -130,6 +153,8 @@ tags.getRemovedItems() // [existingTag]
 Events are raised inside aggregates and dispatched by the infrastructure layer after successful persistence.
 
 ```ts
+import { DomainEvents } from "archstone/domain/enterprise"
+
 // register a handler
 DomainEvents.register(
   (event) => sendWelcomeEmail(event as UserCreatedEvent),
@@ -146,6 +171,8 @@ DomainEvents.dispatchEventsForAggregate(user.id)
 Repositories are defined as interfaces in the application layer. Implementations live in infrastructure.
 
 ```ts
+import { Repository, Creatable } from "archstone/domain/application"
+
 // application/repositories/user-repository.ts
 export interface UserRepository extends Repository<User> {
   findByEmail(email: string): Promise<User | null>
@@ -155,19 +182,14 @@ export interface UserRepository extends Repository<User> {
 export interface AuditRepository extends Creatable<AuditLog> {}
 ```
 
-## Getting Started
+## Contributing
 
-```bash
-bun install
-bun test
-```
+Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) first.
 
-## Tech
+## Code of Conduct
 
-- [Bun](https://bun.sh) — runtime, bundler, and test runner
-- TypeScript 5 with strict mode
-- Zero runtime dependencies
+This project follows the [Contributor Covenant](./CODE_OF_CONDUCT.md).
 
 ## License
 
-MIT
+MIT — see [LICENSE](./LICENSE).

package/dist/core/index.js

@@ -1,118 +1,13 @@
 // @bun
+import {
+  ValueObject,
+  WatchedList,
+  left,
+  right
+} from "../shared/chunk-833sxwt1.js";
 import {
   UniqueEntityId
 } from "../shared/chunk-wzqmg7ms.js";
-
-// src/core/either.ts
-class Left {
-  value;
-  constructor(value) {
-    this.value = value;
-  }
-  isRight() {
-    return false;
-  }
-  isLeft() {
-    return true;
-  }
-}
-
-class Right {
-  value;
-  constructor(value) {
-    this.value = value;
-  }
-  isRight() {
-    return true;
-  }
-  isLeft() {
-    return false;
-  }
-}
-var left = (value) => new Left(value);
-var right = (value) => new Right(value);
-// src/core/value-object.ts
-class ValueObject {
-  props;
-  constructor(props) {
-    this.props = props;
-  }
-  equals(other) {
-    return JSON.stringify(this.props) === JSON.stringify(other.props);
-  }
-}
-// src/core/watched-list.ts
-class WatchedList {
-  currentItems;
-  initial;
-  new;
-  removed;
-  constructor(initialItems) {
-    this.currentItems = initialItems ?? [];
-    this.initial = initialItems ?? [];
-    this.new = [];
-    this.removed = [];
-  }
-  getItems() {
-    return this.currentItems;
-  }
-  getNewItems() {
-    return this.new;
-  }
-  getRemovedItems() {
-    return this.removed;
-  }
-  exists(item) {
-    return this.isCurrentItem(item);
-  }
-  add(item) {
-    if (this.isRemovedItem(item)) {
-      this.removeFromRemoved(item);
-    }
-    if (!(this.isNewItem(item) || this.wasAddedInitially(item))) {
-      this.new.push(item);
-    }
-    if (!this.isCurrentItem(item)) {
-      this.currentItems.push(item);
-    }
-  }
-  remove(item) {
-    this.removeFromCurrent(item);
-    if (this.isNewItem(item)) {
-      this.removeFromNew(item);
-      return;
-    }
-    if (!this.isRemovedItem(item)) {
-      this.removed.push(item);
-    }
-  }
-  update(items) {
-    this.new = items.filter((a) => !this.getItems().some((b) => this.compareItems(a, b)));
-    this.removed = this.getItems().filter((a) => !items.some((b) => this.compareItems(a, b)));
-    this.currentItems = items;
-  }
-  isCurrentItem(item) {
-    return this.currentItems.some((v) => this.compareItems(item, v));
-  }
-  isNewItem(item) {
-    return this.new.some((v) => this.compareItems(item, v));
-  }
-  isRemovedItem(item) {
-    return this.removed.some((v) => this.compareItems(item, v));
-  }
-  removeFromNew(item) {
-    this.new = this.new.filter((v) => !this.compareItems(v, item));
-  }
-  removeFromCurrent(item) {
-    this.currentItems = this.currentItems.filter((v) => !this.compareItems(item, v));
-  }
-  removeFromRemoved(item) {
-    this.removed = this.removed.filter((v) => !this.compareItems(item, v));
-  }
-  wasAddedInitially(item) {
-    return this.initial.some((v) => this.compareItems(item, v));
-  }
-}
 export {
   right,
   left,

package/dist/domain/index.js

@@ -1,4 +1,5 @@
 // @bun
+import"../shared/chunk-x296z7h1.js";
 import"../shared/chunk-wsjyhnpq.js";
 import {
   AggregateRoot,

package/dist/index.d.ts

@@ -0,0 +1,637 @@
+/**
+* Represents the left side of an {@link Either} — conventionally used for
+* failure or error values.
+*
+* @template L - The type of the failure value
+* @template R - The type of the success value
+*/
+declare class Left<
+	L,
+	R
+> {
+	readonly value: L;
+	constructor(value: L);
+	isRight(): this is Right<L, R>;
+	isLeft(): this is Left<L, R>;
+}
+/**
+* Represents the right side of an {@link Either} — conventionally used for
+* success values.
+*
+* @template L - The type of the failure value
+* @template R - The type of the success value
+*/
+declare class Right<
+	L,
+	R
+> {
+	readonly value: R;
+	constructor(value: R);
+	isRight(): this is Right<L, R>;
+	isLeft(): this is Left<L, R>;
+}
+/**
+* A discriminated union that represents a value of one of two possible types.
+*
+* Commonly used as a type-safe alternative to throwing exceptions — the left
+* side carries an error, and the right side carries a success value.
+*
+* Use the {@link left} and {@link right} helper functions to construct values,
+* and `isLeft()` / `isRight()` to narrow the type.
+*
+* @template L - The type of the failure value
+* @template R - The type of the success value
+*
+* @example
+* ```ts
+* type FindUserResult = Either<NotFoundError, User>
+*
+* function findUser(id: string): FindUserResult {
+*   const user = db.find(id)
+*   if (!user) return left(new NotFoundError("User", id))
+*   return right(user)
+* }
+*
+* const result = findUser("123")
+*
+* if (result.isLeft()) {
+*   console.error(result.value) // NotFoundError
+* } else {
+*   console.log(result.value)   // User
+* }
+* ```
+*/
+type Either<
+	L,
+	R
+> = Left<L, R> | Right<L, R>;
+/**
+* Constructs a {@link Left} value, representing a failure.
+*
+* @param value - The error or failure value
+*/
+declare const left: <
+	L,
+	R
+>(value: L) => Either<L, R>;
+/**
+* Constructs a {@link Right} value, representing a success.
+*
+* @param value - The success value
+*/
+declare const right: <
+	L,
+	R
+>(value: R) => Either<L, R>;
+/**
+* Make some property optional on type
+*
+* @example
+* ```typescript
+* type Post {
+*  id: string;
+*  name: string;
+*  email: string;
+* }
+*
+* Optional<Post, 'id' | 'email'>
+* ```
+*/
+type Optional<
+	T,
+	K extends keyof T
+> = Pick<Partial<T>, K> & Omit<T, K>;
+/**
+* Represents a unique identifier for a domain entity.
+*
+* Wraps a UUID v7 string, which is time-sortable and ideal for database
+* indexing. A new identifier is generated automatically if no value is provided.
+*
+* @example
+* ```ts
+* // auto-generated
+* const id = new UniqueEntityId()
+*
+* // from existing value (e.g. reconstructing from database)
+* const id = new UniqueEntityId("0195d810-5b3e-7000-8e3e-1a2b3c4d5e6f")
+* ```
+*/
+declare class UniqueEntityId {
+	private readonly value;
+	constructor(value?: string);
+	/**
+	* Returns the identifier as a primitive string.
+	* Useful for serialization and database persistence.
+	*/
+	toValue(): string;
+	/**
+	* Returns the string representation of the identifier.
+	*/
+	toString(): string;
+	/**
+	* Compares this identifier with another by value equality.
+	*
+	* @param id - The identifier to compare against
+	* @returns `true` if both identifiers have the same value
+	*/
+	equals(id: UniqueEntityId): boolean;
+}
+/**
+* Base class for all value objects in the domain.
+*
+* A value object is an object defined entirely by its attributes — it has no
+* identity. Two value objects are considered equal if all their properties
+* are deeply equal, regardless of reference.
+*
+* Value objects should be immutable. Avoid mutating `props` directly;
+* instead, create a new instance with the updated values.
+*
+* All value objects must implement a static `create` factory method to
+* encapsulate construction and validation logic, keeping the constructor
+* protected from external instantiation.
+*
+* @template Props - The shape of the value object's properties
+*
+* @example
+* ```ts
+* interface EmailProps {
+*   value: string
+* }
+*
+* class Email extends ValueObject<EmailProps> {
+*   get value() { return this.props.value }
+*
+*   static create(email: string): Email {
+*     if (!email.includes("@")) {
+*       throw new ValidationError("Invalid email address.")
+*     }
+*
+*     return new Email({ value: email })
+*   }
+* }
+* ```
+*/
+declare abstract class ValueObject<Props> {
+	protected props: Props;
+	protected constructor(props: Props);
+	/**
+	* Compares this value object with another by deep equality of their properties.
+	*
+	* @param other - The value object to compare against
+	* @returns `true` if both value objects have deeply equal properties
+	*/
+	equals(other: ValueObject<Props>): boolean;
+}
+/**
+* Tracks additions and removals of items in a collection, enabling
+* efficient persistence of only what changed.
+*
+* Commonly used inside aggregate roots to manage one-to-many relationships
+* without rewriting the entire collection on every save — only new and
+* removed items are persisted.
+*
+* Subclasses must implement {@link compareItems} to define equality between items.
+*
+* @template T - The type of items in the list
+*
+* @example
+* ```ts
+* class TagList extends WatchedList<Tag> {
+*   compareItems(a: Tag, b: Tag): boolean {
+*     return a.id.equals(b.id)
+*   }
+*
+*   static create(tags: Tag[]): TagList {
+*     return new TagList(tags)
+*   }
+* }
+*
+* const tags = TagList.create([existingTag])
+*
+* tags.add(newTag)      // tracked as new
+* tags.remove(oldTag)   // tracked as removed
+*
+* tags.getNewItems()     // [newTag]
+* tags.getRemovedItems() // [oldTag]
+* ```
+*/
+declare abstract class WatchedList<T> {
+	protected currentItems: T[];
+	protected initial: T[];
+	protected new: T[];
+	protected removed: T[];
+	constructor(initialItems?: T[]);
+	/**
+	* Returns all current items in the list.
+	*/
+	getItems(): T[];
+	/**
+	* Returns items that were added since the list was created.
+	*/
+	getNewItems(): T[];
+	/**
+	* Returns items that were removed since the list was created.
+	*/
+	getRemovedItems(): T[];
+	/**
+	* Returns whether the given item exists in the current list.
+	*
+	* @param item - The item to check
+	*/
+	exists(item: T): boolean;
+	/**
+	* Adds an item to the list, tracking it as new if it wasn't in the initial set.
+	* If the item was previously removed, it is restored.
+	*
+	* @param item - The item to add
+	*/
+	add(item: T): void;
+	/**
+	* Removes an item from the list, tracking it as removed if it was in the initial set.
+	*
+	* @param item - The item to remove
+	*/
+	remove(item: T): void;
+	/**
+	* Replaces the entire list with a new set of items, automatically
+	* computing what was added and what was removed.
+	*
+	* @param items - The new set of items
+	*/
+	update(items: T[]): void;
+	private isCurrentItem;
+	private isNewItem;
+	private isRemovedItem;
+	private removeFromNew;
+	private removeFromCurrent;
+	private removeFromRemoved;
+	private wasAddedInitially;
+}
+/**
+* Contract for entities that can be created.
+*
+* @template T - The entity type
+*/
+interface Creatable<T> {
+	/**
+	* Persists a new entity for the first time.
+	*
+	* @param entity - The entity to create
+	*/
+	create(entity: T): Promise<void>;
+}
+/**
+* Contract for entities that can be deleted.
+*
+* @template T - The entity type
+*/
+interface Deletable<T> {
+	/**
+	* Deletes an entity from the repository.
+	*
+	* @param entity - The entity to delete
+	*/
+	delete(entity: T): Promise<void>;
+}
+/**
+* Contract for entities that can be retrieved by their unique identifier.
+*
+* @template T - The entity type
+*/
+interface Findable<T> {
+	/**
+	* Finds an entity by its unique identifier.
+	*
+	* @param id - The unique identifier of the entity
+	* @returns The entity if found, `null` otherwise
+	*/
+	findById(id: string): Promise<T | null>;
+}
+/**
+* Contract for entities that can be persisted.
+*
+* @template T - The entity type
+*/
+interface Saveable<T> {
+	/**
+	* Persists an existing entity.
+	*
+	* @param entity - The entity to save
+	*/
+	save(entity: T): Promise<void>;
+}
+/**
+* Full CRUD repository contract, composing all segregated interfaces.
+*
+* Use this when the repository needs to support all operations. For more
+* constrained repositories, prefer composing only the interfaces you need.
+*
+* @template T - The entity type
+*
+* @example
+* ```ts
+* // full CRUD
+* interface UserRepository extends Repository<User> {
+*   findByEmail(email: string): Promise<User | null>
+* }
+*
+* // read-only
+* interface ReportRepository extends Findable<Report> {
+*   findByPeriod(start: Date, end: Date): Promise<Report[]>
+* }
+*
+* // append-only
+* interface AuditRepository extends Creatable<AuditLog> {}
+* ```
+*/
+interface Repository<T> extends Findable<T>, Saveable<T>, Creatable<T>, Deletable<T> {}
+/**
+* Base contract for all use case errors.
+*
+* Implement this interface to define semantic, domain-aware errors
+* that can be returned as the left side of an {@link Either}.
+*
+* @example
+* ```ts
+* class UserNotFoundError implements UseCaseError {
+*   message = "User not found."
+* }
+*
+* type FindUserResult = Either<UserNotFoundError, User>
+* ```
+*/
+interface UseCaseError {
+	message: string;
+}
+/**
+* Represents the expected output shape of any use case.
+* Always an {@link Either} — left for errors, right for success.
+*/
+type UseCaseOutput = Either<UseCaseError | never, unknown | null>;
+/**
+* Base contract for all application use cases.
+*
+* A use case orchestrates domain logic for a single application operation.
+* It receives a typed input, interacts with the domain, and returns an
+* {@link Either} — never throwing exceptions directly.
+*
+* The left side carries a {@link UseCaseError} on failure.
+* The right side carries the success value.
+*
+* @template Input - The shape of the data required to execute the use case
+* @template Output - The expected {@link Either} output, constrained to {@link UseCaseOutput}
+*
+* @example
+* ```ts
+* type Input = { userId: string }
+* type Output = Either<UserNotFoundError, User>
+*
+* class GetUserUseCase implements UseCase<Input, Output> {
+*   constructor(private userRepository: UserRepository) {}
+*
+*   async execute({ userId }: Input): Promise<Output> {
+*     const user = await this.userRepository.findById(userId)
+*     if (!user) return left(new UserNotFoundError(userId))
+*     return right(user)
+*   }
+* }
+* ```
+*/
+interface UseCase<
+	Input,
+	Output extends UseCaseOutput
+> {
+	execute(input: Input): Promise<Output>;
+}
+/**
+* Base contract for all domain events.
+*
+* A domain event represents something meaningful that happened in the domain.
+* Events are raised by aggregate roots and dispatched after successful persistence,
+* enabling decoupled side effects such as notifications, projections, and integrations.
+*
+* @example
+* ```ts
+* class UserCreatedEvent implements DomainEvent {
+*   occurredAt = new Date()
+*
+*   constructor(private readonly user: User) {}
+*
+*   getAggregateId(): UniqueEntityId {
+*     return this.user.id
+*   }
+* }
+* ```
+*/
+interface DomainEvent {
+	/**
+	* Returns the identifier of the aggregate root that raised this event.
+	*/
+	getAggregateId(): UniqueEntityId;
+	/**
+	* The date and time when the event occurred.
+	*/
+	occurredAt: Date;
+}
+/**
+* Callback function invoked when a domain event is dispatched.
+*/
+type DomainEventCallback = (event: DomainEvent) => void;
+/**
+* Central registry and dispatcher for domain events.
+*
+* Aggregates register themselves for dispatch after raising events.
+* The infrastructure layer is responsible for calling {@link dispatchEventsForAggregate}
+* after successfully persisting an aggregate, ensuring events are only
+* dispatched after a successful transaction.
+*
+* @example
+* ```ts
+* // register a handler
+* DomainEvents.register(
+*   (event) => sendWelcomeEmail(event as UserCreatedEvent),
+*   UserCreatedEvent.name,
+* )
+*
+* // dispatch after persistence
+* await userRepository.create(user)
+* DomainEvents.dispatchEventsForAggregate(user.id)
+* ```
+*/
+declare class DomainEventsImplementation {
+	private readonly handlersMap;
+	private readonly markedAggregates;
+	/**
+	* Marks an aggregate root to have its events dispatched.
+	* Called automatically by {@link AggregateRoot.addDomainEvent}.
+	*
+	* @param aggregate - The aggregate to mark for dispatch
+	*/
+	markAggregateForDispatch(aggregate: AggregateRoot<unknown>): void;
+	/**
+	* Dispatches all pending events for the aggregate with the given id,
+	* clears its events, and removes it from the dispatch list.
+	*
+	* Should be called by the infrastructure layer after persisting the aggregate.
+	*
+	* @param id - The identifier of the aggregate to dispatch events for
+	*/
+	dispatchEventsForAggregate(id: UniqueEntityId): void;
+	/**
+	* Registers an event handler for a given event class name.
+	*
+	* @param callback - The function to invoke when the event is dispatched
+	* @param eventClassName - The name of the event class to listen for
+	*/
+	register(callback: DomainEventCallback, eventClassName: string): void;
+	/**
+	* Removes all registered event handlers.
+	* Useful for test isolation.
+	*/
+	clearHandlers(): void;
+	/**
+	* Removes all aggregates from the dispatch list.
+	* Useful for test isolation.
+	*/
+	clearMarkedAggregates(): void;
+	private dispatchAggregateEvents;
+	private removeAggregateFromMarkedDispatchList;
+	private findMarkedAggregateByID;
+	private dispatch;
+}
+/**
+* Singleton instance of the domain events registry.
+* Use this to register handlers and dispatch events across the application.
+*/
+declare const DomainEvents: DomainEventsImplementation;
+/**
+* Base contract for all 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.
+*
+* All handlers must implement {@link setupSubscriptions} to register
+* their callbacks in the {@link DomainEvents} registry.
+*
+* @example
+* ```ts
+* class OnUserCreated implements EventHandler {
+*   constructor(private readonly mailer: Mailer) {}
+*
+*   setupSubscriptions(): void {
+*     DomainEvents.register(
+*       (event) => this.sendWelcomeEmail(event as UserCreatedEvent),
+*       UserCreatedEvent.name,
+*     )
+*   }
+*
+*   private async sendWelcomeEmail(event: UserCreatedEvent): Promise<void> {
+*     await this.mailer.send(event.user.email)
+*   }
+* }
+* ```
+*/
+interface EventHandler {
+	/**
+	* Registers all event subscriptions for this handler.
+	* Should be called once during application bootstrap.
+	*/
+	setupSubscriptions(): void;
+}
+/**
+* Base class for all domain entities.
+*
+* An entity is an object defined by its identity rather than its attributes.
+* Two entities are considered equal if they share the same `id`, regardless
+* of their other properties.
+*
+* All entities must implement a static `create` factory method to encapsulate
+* construction logic and keep the constructor protected.
+*
+* @template Props - The shape of the entity's properties
+*
+* @example
+* ```ts
+* interface UserProps {
+*   id: UniqueEntityId
+*   name: string
+*   email: string
+*   createdAt: Date
+* }
+*
+* class User extends Entity<UserProps> {
+*   get name() { return this.props.name }
+*   get email() { return this.props.email }
+*
+*   static create(props: Optional<UserProps, "id" | "createdAt">): User {
+*     return new User(
+*       { ...props, createdAt: props.createdAt ?? new Date() },
+*       props.id ?? new UniqueEntityId(),
+*     )
+*   }
+* }
+* ```
+*/
+declare abstract class Entity<Props> {
+	private readonly _id;
+	protected props: Props;
+	get id(): UniqueEntityId;
+	protected constructor(props: Props, id?: UniqueEntityId);
+	/**
+	* Compares this entity with another by identity.
+	*
+	* @param entity - The entity to compare against
+	* @returns `true` if both entities share the same `id`
+	*/
+	equals(entity: Entity<unknown>): boolean;
+}
+/**
+* Base class for all aggregate roots in the domain.
+*
+* An aggregate root is the entry point to an aggregate — a cluster of domain
+* objects that are treated as a single unit. It is responsible for enforcing
+* invariants and coordinating domain events within its boundary.
+*
+* Domain events are collected internally and dispatched after the aggregate
+* is persisted, ensuring side effects only occur after a successful transaction.
+*
+* @template Props - The shape of the aggregate's properties
+*
+* @example
+* ```ts
+* class User extends AggregateRoot<UserProps> {
+*   static create(props: Optional<UserProps, "id" | "createdAt">): User {
+*     const user = new User(
+*       { ...props, createdAt: props.createdAt ?? new Date() },
+*       props.id ?? new UniqueEntityId(),
+*     )
+*
+*     user.addDomainEvent(new UserCreatedEvent(user))
+*
+*     return user
+*   }
+* }
+* ```
+*/
+declare abstract class AggregateRoot<Props> extends Entity<Props> {
+	private readonly _domainEvents;
+	/**
+	* Returns all domain events that have been raised by this aggregate
+	* and are pending dispatch.
+	*/
+	get domainEvents(): DomainEvent[];
+	/**
+	* Registers a domain event to be dispatched after the aggregate is persisted.
+	* Automatically marks this aggregate for dispatch in the {@link DomainEvents} registry.
+	*
+	* @param domainEvent - The domain event to register
+	*/
+	protected addDomainEvent(domainEvent: DomainEvent): void;
+	/**
+	* Clears all pending domain events from this aggregate.
+	* Should be called by the infrastructure layer after events are dispatched.
+	*/
+	clearEvents(): void;
+}
+export { right, left, WatchedList, ValueObject, UseCaseError, UseCase, UniqueEntityId, Saveable, Repository, Optional, Findable, EventHandler, Entity, Either, DomainEvents, DomainEvent, Deletable, Creatable, AggregateRoot };

package/dist/index.js

@@ -0,0 +1,27 @@
+// @bun
+import {
+  ValueObject,
+  WatchedList,
+  left,
+  right
+} from "./shared/chunk-833sxwt1.js";
+import"./shared/chunk-x296z7h1.js";
+import"./shared/chunk-wsjyhnpq.js";
+import {
+  AggregateRoot,
+  DomainEvents,
+  Entity
+} from "./shared/chunk-9cq8r162.js";
+import {
+  UniqueEntityId
+} from "./shared/chunk-wzqmg7ms.js";
+export {
+  right,
+  left,
+  WatchedList,
+  ValueObject,
+  UniqueEntityId,
+  Entity,
+  DomainEvents,
+  AggregateRoot
+};

package/dist/shared/chunk-833sxwt1.js

@@ -0,0 +1,112 @@
+// @bun
+// src/core/either.ts
+class Left {
+  value;
+  constructor(value) {
+    this.value = value;
+  }
+  isRight() {
+    return false;
+  }
+  isLeft() {
+    return true;
+  }
+}
+
+class Right {
+  value;
+  constructor(value) {
+    this.value = value;
+  }
+  isRight() {
+    return true;
+  }
+  isLeft() {
+    return false;
+  }
+}
+var left = (value) => new Left(value);
+var right = (value) => new Right(value);
+// src/core/value-object.ts
+class ValueObject {
+  props;
+  constructor(props) {
+    this.props = props;
+  }
+  equals(other) {
+    return JSON.stringify(this.props) === JSON.stringify(other.props);
+  }
+}
+// src/core/watched-list.ts
+class WatchedList {
+  currentItems;
+  initial;
+  new;
+  removed;
+  constructor(initialItems) {
+    this.currentItems = initialItems ?? [];
+    this.initial = initialItems ?? [];
+    this.new = [];
+    this.removed = [];
+  }
+  getItems() {
+    return this.currentItems;
+  }
+  getNewItems() {
+    return this.new;
+  }
+  getRemovedItems() {
+    return this.removed;
+  }
+  exists(item) {
+    return this.isCurrentItem(item);
+  }
+  add(item) {
+    if (this.isRemovedItem(item)) {
+      this.removeFromRemoved(item);
+    }
+    if (!(this.isNewItem(item) || this.wasAddedInitially(item))) {
+      this.new.push(item);
+    }
+    if (!this.isCurrentItem(item)) {
+      this.currentItems.push(item);
+    }
+  }
+  remove(item) {
+    this.removeFromCurrent(item);
+    if (this.isNewItem(item)) {
+      this.removeFromNew(item);
+      return;
+    }
+    if (!this.isRemovedItem(item)) {
+      this.removed.push(item);
+    }
+  }
+  update(items) {
+    this.new = items.filter((a) => !this.getItems().some((b) => this.compareItems(a, b)));
+    this.removed = this.getItems().filter((a) => !items.some((b) => this.compareItems(a, b)));
+    this.currentItems = items;
+  }
+  isCurrentItem(item) {
+    return this.currentItems.some((v) => this.compareItems(item, v));
+  }
+  isNewItem(item) {
+    return this.new.some((v) => this.compareItems(item, v));
+  }
+  isRemovedItem(item) {
+    return this.removed.some((v) => this.compareItems(item, v));
+  }
+  removeFromNew(item) {
+    this.new = this.new.filter((v) => !this.compareItems(v, item));
+  }
+  removeFromCurrent(item) {
+    this.currentItems = this.currentItems.filter((v) => !this.compareItems(item, v));
+  }
+  removeFromRemoved(item) {
+    this.removed = this.removed.filter((v) => !this.compareItems(item, v));
+  }
+  wasAddedInitially(item) {
+    return this.initial.some((v) => this.compareItems(item, v));
+  }
+}
+export { left, right, ValueObject, WatchedList };

package/dist/shared/chunk-x296z7h1.js

@@ -0,0 +1 @@
+// @bun

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "archstone",
-  "version": "1.0.0",
+  "description": "TypeScript architecture foundation for backend services based on Domain-Driven Design and Clean Architecture",
+  "version": "1.0.2",
   "type": "module",
   "private": false,
   "files": [
     "dist"
   ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
     "./core": {
       "import": {
         "types": "./dist/core/index.d.ts",
@@ -33,6 +42,33 @@
     },
     "./package.json": "./package.json"
   },
+  "keywords": [
+    "ddd",
+    "domain-driven-design",
+    "clean-architecture",
+    "typescript",
+    "entity",
+    "aggregate",
+    "value-object",
+    "either",
+    "domain-events",
+    "repository",
+    "use-case",
+    "bun"
+  ],
+  "author": {
+    "name": "João Henrique Benatti Coimbra",
+    "url": "https://github.com/joao-coimbra"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/joao-coimbra/archstone#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joao-coimbra/archstone.git"
+  },
+  "bugs": {
+    "url": "https://github.com/joao-coimbra/archstone/issues"
+  },
   "scripts": {
     "build": "bunup",
     "dev": "bunup --watch",