archstone 1.0.1 → 1.0.3

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,51 +1,47 @@
+<div align="center">
+
 # archstone
 
-A TypeScript-first architecture foundation for backend services, built around Domain-Driven Design (DDD) and Clean Architecture principles.
+**TypeScript architecture foundation for backend services.**
+Stop re-implementing DDD boilerplate. Focus on your domain.
 
-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.
+[![npm](https://img.shields.io/npm/v/archstone?style=flat-square&color=black)](https://www.npmjs.com/package/archstone)
+[![license](https://img.shields.io/badge/license-MIT-black?style=flat-square)](./LICENSE)
+[![typescript](https://img.shields.io/badge/TypeScript-5-black?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)
 
-## Layers
+</div>
 
+---
+
+Archstone gives you the structural pieces of **Domain-Driven Design** and **Clean Architecture** — entities, value objects, aggregates, domain events, use cases, and repository contracts — so every project starts from a solid, consistent foundation.
+
+## Install
+
+```bash
+bun add archstone
+# or
+npm install archstone
 ```
-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>
-```
 
-## Core Concepts
+## At a Glance
+
+| Building block | What it does |
+|---|---|
+| `Entity` / `AggregateRoot` | Identity-based domain objects; aggregates raise domain events |
+| `ValueObject` | Equality by value, not reference |
+| `UniqueEntityId` | UUID v7 identity wrapper |
+| `WatchedList` | Tracks additions and removals in a collection |
+| `Either` | Functional error handling — no throwing in use cases |
+| `UseCase` | Contract for application use cases returning `Either` |
+| `Repository` | CRUD interface contracts — implementations live in infra |
 
-### Either — functional error handling
+## Usage
 
-Use cases never throw. They return an `Either<Error, Value>` — left for failure, right for success.
+### Either — handle errors without throwing
 
 ```ts
-import { Either, left, right } from "@/core/either"
+import { Either, left, right } from 'archstone/core'
 
 type Result = Either<UserNotFoundError, User>
 
@@ -55,19 +51,20 @@ async function findUser(id: string): Promise<Result> {
   return right(user)
 }
 
-const result = await findUser("123")
-if (result.isLeft()) console.error(result.value) // UserNotFoundError
-else console.log(result.value)                    // User
-```
+const result = await findUser('123')
 
-### Entity & AggregateRoot
+if (result.isLeft()) {
+  console.error(result.value) // UserNotFoundError
+} else {
+  console.log(result.value)   // User
+}
+```
 
-Entities are defined by identity. Aggregates extend that with domain event support.
+### Entity & AggregateRoot — model your domain
 
 ```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
@@ -77,24 +74,23 @@ 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(),
+    })
     order.addDomainEvent(new OrderCreatedEvent(order))
     return order
   }
 }
 ```
 
-### ValueObject
-
-Value objects are equal by their properties, not by reference.
+### ValueObject — equality by value
 
 ```ts
-import { ValueObject } from "@/core/value-object"
+import { ValueObject } from 'archstone/core'
 
 interface EmailProps { value: string }
 
@@ -102,17 +98,21 @@ 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() })
   }
 }
-```
 
-### WatchedList
+const a = Email.create('user@example.com')
+const b = Email.create('user@example.com')
+a.equals(b) // true
+```
 
-Track additions and removals in a collection without rewriting the whole thing on save.
+### WatchedList — track collection changes
 
 ```ts
+import { WatchedList } from 'archstone/core'
+
 class TagList extends WatchedList<Tag> {
   compareItems(a: Tag, b: Tag) { return a.id.equals(b.id) }
 }
@@ -125,49 +125,82 @@ 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
-// register a handler
+import { DomainEvents } from 'archstone/domain/enterprise'
+
+// Register a handler
 DomainEvents.register(
   (event) => sendWelcomeEmail(event as UserCreatedEvent),
   UserCreatedEvent.name,
 )
 
-// infrastructure dispatches after persisting
+// Dispatch after persisting the aggregate
 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 infra out of your domain
 
 ```ts
-// application/repositories/user-repository.ts
+import { Repository, Creatable } from 'archstone/domain/application'
+
+// Compose the interface you need
 export interface UserRepository extends Repository<User> {
   findByEmail(email: string): Promise<User | null>
 }
 
-// or compose only what you need
+// Or only what you need
 export interface AuditRepository extends Creatable<AuditLog> {}
 ```
 
-## Getting Started
+## Package Exports
 
-```bash
-bun install
-bun test
+```
+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
+```
+
+## Layer Architecture
+
+```
+src/
+├── core/                   # Zero domain knowledge — pure utilities
+│   ├── either.ts
+│   ├── value-object.ts
+│   ├── unique-entity-id.ts
+│   ├── watched-list.ts
+│   └── types/optional.ts
+│
+└── domain/
+    ├── enterprise/         # Pure domain model — no framework deps
+    │   ├── entities/
+    │   │   ├── entity.ts
+    │   │   └── aggregate-root.ts
+    │   └── events/
+    │       ├── domain-event.ts
+    │       ├── domain-events.ts
+    │       └── event-handler.ts
+    │
+    └── application/        # Use cases & repository contracts
+        ├── use-cases/
+        │   ├── use-case.ts
+        │   └── use-case.error.ts
+        └── repositories/
+            ├── repository.ts
+            ├── findable.ts
+            ├── creatable.ts
+            ├── saveable.ts
+            └── deletable.ts
 ```
 
-## Tech
+---
 
-- [Bun](https://bun.sh) — runtime, bundler, and test runner
-- TypeScript 5 with strict mode
-- Zero runtime dependencies
+<div align="center">
 
-## License
+[Contributing](./CONTRIBUTING.md) · [Code of Conduct](./CODE_OF_CONDUCT.md) · [MIT License](./LICENSE)
 
-MIT
+</div>

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "archstone",
-  "version": "1.0.1",
+  "description": "TypeScript architecture foundation for backend services based on Domain-Driven Design and Clean Architecture",
+  "version": "1.0.3",
   "type": "module",
   "private": false,
   "files": [
@@ -41,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",