archstone 1.0.2 → 1.0.4

package/README.md

@@ -1,94 +1,97 @@
-# archstone
+<div align="center">
 
-[![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)
+# Archstone
 
-> TypeScript architecture foundation for backend services based on Domain-Driven Design (DDD) and Clean Architecture.
+### The TypeScript foundation for serious backend services.
 
-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.
+Build on Domain-Driven Design and Clean Architecture — without writing the same boilerplate on every project.
 
-## Installation
+<br />
 
-```bash
-bun add archstone
-# or
-npm install archstone
-```
+[![npm version](https://img.shields.io/npm/v/archstone?style=for-the-badge&logo=npm&color=CB3837&logoColor=white)](https://www.npmjs.com/package/archstone)
+[![license](https://img.shields.io/badge/license-MIT-22C55E?style=for-the-badge)](./LICENSE)
+[![typescript](https://img.shields.io/badge/TypeScript-5-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![bun](https://img.shields.io/badge/Bun-ready-F9F1E1?style=for-the-badge&logo=bun&logoColor=black)](https://bun.sh)
 
-## Packages
+<br />
 
-| 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 |
+</div>
 
-## Architecture
+---
+
+## Why archstone?
 
+Every backend project in DDD needs the same structural pieces — and most teams rewrite them from scratch each time. Archstone gives you a **battle-tested, zero-dependency set of base classes and contracts** so you can skip the boilerplate and go straight to modeling your domain.
+
+```ts
+// ❌ Before — scattered, inconsistent, no error contract
+class User { id: string }
+function createUser() { throw new Error('not found') }
+
+// ✅ After — structured, predictable, type-safe
+class User extends AggregateRoot<UserProps> { ... }
+async function createUser(): Promise<Either<NotFoundError, User>> { ... }
 ```
-src/
-├── core/          # Language-level utilities with no domain knowledge
-│   ├── either.ts              # Functional error handling (Left / Right)
-│   ├── value-object.ts        # Base class for value objects
-│   ├── unique-entity-id.ts    # UUID v7 identity wrapper
-│   ├── watched-list.ts        # Change-tracked collection for aggregates
-│   └── types/
-│       └── optional.ts        # Optional<T, K> utility type
-│
-└── domain/
-    ├── enterprise/            # Pure domain model — no framework deps
-    │   ├── entities/
-    │   │   ├── entity.ts          # Identity-based base entity
-    │   │   └── aggregate-root.ts  # Event-raising aggregate base
-    │   └── events/
-    │       ├── domain-event.ts    # DomainEvent interface
-    │       ├── domain-events.ts   # Singleton registry & dispatcher
-    │       └── event-handler.ts   # EventHandler interface
-    │
-    └── application/           # Orchestration — use cases & repository contracts
-        ├── use-cases/
-        │   ├── use-case.ts        # UseCase<Input, Output> interface
-        │   └── use-case.error.ts  # Base error type for use case failures
-        └── repositories/
-            ├── repository.ts      # Full CRUD contract (composed)
-            ├── findabe.ts         # Findable<T>
-            ├── creatable.ts       # Creatable<T>
-            ├── saveble.ts         # Saveable<T>
-            └── deletable.ts       # Deletable<T>
+
+---
+
+## Features
+
+- **`Either`** — functional error handling; use cases never throw
+- **`Entity` / `AggregateRoot`** — identity-based domain objects with built-in event support
+- **`ValueObject`** — equality by value, not reference
+- **`UniqueEntityId`** — UUID v7 identity, consistent across your entire domain
+- **`WatchedList`** — track additions and removals in collections without overwriting persistence
+- **`UseCase`** — typed contract for application logic
+- **Repository contracts** — define your interface in the domain; implement in infrastructure
+
+---
+
+## Install
+
+```bash
+bun add archstone
+# or
+npm install archstone
 ```
 
-## Core Concepts
+> Zero runtime dependencies. Pure TypeScript.
 
-### Either — functional error handling
+---
 
-Use cases never throw. They return an `Either<Error, Value>` — left for failure, right for success.
+## Usage
+
+### `Either` — stop throwing, start returning
 
 ```ts
-import { Either, left, right } from "archstone/core"
+import { Either, left, right } from 'archstone/core'
 
-type Result = Either<UserNotFoundError, User>
+type FindUserResult = Either<UserNotFoundError, User>
 
-async function findUser(id: string): Promise<Result> {
+async function findUser(id: string): Promise<FindUserResult> {
   const user = await repo.findById(id)
+
   if (!user) return left(new UserNotFoundError(id))
   return right(user)
 }
 
-const result = await findUser("123")
-if (result.isLeft()) console.error(result.value) // UserNotFoundError
-else console.log(result.value)                    // User
+// The caller always handles both cases — no surprises
+const result = await findUser('123')
+
+if (result.isLeft()) {
+  console.error(result.value) // UserNotFoundError
+} else {
+  console.log(result.value)   // User ✓
+}
 ```
 
-### Entity & AggregateRoot
+---
 
-Entities are defined by identity. Aggregates extend that with domain event support.
+### `Entity` & `AggregateRoot` — model your domain
 
 ```ts
-import { AggregateRoot } from "archstone/domain/enterprise"
-import { UniqueEntityId, Optional } from "archstone/core"
+import { AggregateRoot } from 'archstone/domain/enterprise'
+import { UniqueEntityId, Optional } from 'archstone/core'
 
 interface OrderProps {
   customerId: UniqueEntityId
@@ -98,24 +101,27 @@ interface OrderProps {
 
 class Order extends AggregateRoot<OrderProps> {
   get customerId() { return this.props.customerId }
-  get total() { return this.props.total }
+  get total()      { return this.props.total }
 
-  static create(props: Optional<OrderProps, "createdAt">): Order {
-    const order = new Order(
-      { ...props, createdAt: props.createdAt ?? new Date() },
-    )
+  static create(props: Optional<OrderProps, 'createdAt'>): Order {
+    const order = new Order({
+      ...props,
+      createdAt: props.createdAt ?? new Date(),
+    })
+
+    // Raise domain events from inside the aggregate
     order.addDomainEvent(new OrderCreatedEvent(order))
     return order
   }
 }
 ```
 
-### ValueObject
+---
 
-Value objects are equal by their properties, not by reference.
+### `ValueObject` — equality that makes sense
 
 ```ts
-import { ValueObject } from "archstone/core"
+import { ValueObject } from 'archstone/core'
 
 interface EmailProps { value: string }
 
@@ -123,18 +129,23 @@ class Email extends ValueObject<EmailProps> {
   get value() { return this.props.value }
 
   static create(raw: string): Email {
-    if (!raw.includes("@")) throw new Error("Invalid email")
+    if (!raw.includes('@')) throw new Error('Invalid email')
     return new Email({ value: raw.toLowerCase() })
   }
 }
+
+const a = Email.create('user@example.com')
+const b = Email.create('user@example.com')
+
+a.equals(b) // ✅ true — compared by value, not reference
 ```
 
-### WatchedList
+---
 
-Track additions and removals in a collection without rewriting the whole thing on save.
+### `WatchedList` — persist only what changed
 
 ```ts
-import { WatchedList } from "archstone/core"
+import { WatchedList } from 'archstone/core'
 
 class TagList extends WatchedList<Tag> {
   compareItems(a: Tag, b: Tag) { return a.id.equals(b.id) }
@@ -144,52 +155,100 @@ const tags = new TagList([existingTag])
 tags.add(newTag)
 tags.remove(existingTag)
 
-tags.getNewItems()     // [newTag]
-tags.getRemovedItems() // [existingTag]
+// Send only the diff to your repository — not the whole list
+tags.getNewItems()     // → [newTag]
+tags.getRemovedItems() // → [existingTag]
 ```
 
-### Domain Events
+---
 
-Events are raised inside aggregates and dispatched by the infrastructure layer after successful persistence.
+### Domain Events — decouple side effects
 
 ```ts
-import { DomainEvents } from "archstone/domain/enterprise"
+import { DomainEvents } from 'archstone/domain/enterprise'
 
-// register a handler
+// Register handlers anywhere in your infrastructure layer
 DomainEvents.register(
   (event) => sendWelcomeEmail(event as UserCreatedEvent),
   UserCreatedEvent.name,
 )
 
-// infrastructure dispatches after persisting
+// Dispatch after persistence — events stay inside the aggregate until then
 await userRepository.create(user)
 DomainEvents.dispatchEventsForAggregate(user.id)
 ```
 
-### Repository Contracts
+---
 
-Repositories are defined as interfaces in the application layer. Implementations live in infrastructure.
+### Repository Contracts — keep infrastructure out of your domain
 
 ```ts
-import { Repository, Creatable } from "archstone/domain/application"
+import { Repository, Creatable } from 'archstone/domain/application'
 
-// application/repositories/user-repository.ts
+// Define your contract in the application layer
 export interface UserRepository extends Repository<User> {
   findByEmail(email: string): Promise<User | null>
 }
 
-// or compose only what you need
+// Compose only what you need
 export interface AuditRepository extends Creatable<AuditLog> {}
+
+// Implement anywhere in infrastructure — domain stays clean
 ```
 
-## Contributing
+---
+
+## Package Exports
+
+| Import | 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/
+├── core/                    # Zero domain knowledge — pure language utilities
+│   ├── either.ts            # Left / Right functional result type
+│   ├── value-object.ts      # Value equality base class
+│   ├── unique-entity-id.ts  # UUID v7 identity wrapper
+│   ├── watched-list.ts      # Change-tracked collection
+│   └── 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
+    │
+    └── application/         # Orchestration — use cases & repository contracts
+        ├── use-cases/
+        │   ├── use-case.ts
+        │   └── use-case.error.ts
+        └── repositories/
+            ├── repository.ts
+            ├── findable.ts
+            ├── creatable.ts
+            ├── saveable.ts
+            └── deletable.ts
+```
 
-Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) first.
+---
 
-## Code of Conduct
+<div align="center">
 
-This project follows the [Contributor Covenant](./CODE_OF_CONDUCT.md).
+**Built with care for the TypeScript community.**
 
-## License
+[Contributing](./CONTRIBUTING.md) · [Code of Conduct](./CODE_OF_CONDUCT.md) · [MIT License](./LICENSE)
 
-MIT — see [LICENSE](./LICENSE).
+</div>

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.0.2",
+  "version": "1.0.4",
   "type": "module",
   "private": false,
   "files": [