archstone 1.0.0

package/README.md

@@ -0,0 +1,173 @@
+# archstone
+
+A TypeScript-first architecture foundation for backend services, built around Domain-Driven Design (DDD) and Clean Architecture principles.
+
+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
+
+```
+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
+
+### Either — functional error handling
+
+Use cases never throw. They return an `Either<Error, Value>` — left for failure, right for success.
+
+```ts
+import { Either, left, right } from "@/core/either"
+
+type Result = Either<UserNotFoundError, User>
+
+async function findUser(id: string): Promise<Result> {
+  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
+```
+
+### Entity & AggregateRoot
+
+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"
+
+interface OrderProps {
+  customerId: UniqueEntityId
+  total: number
+  createdAt: Date
+}
+
+class Order extends AggregateRoot<OrderProps> {
+  get customerId() { return this.props.customerId }
+  get total() { return this.props.total }
+
+  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.
+
+```ts
+import { ValueObject } from "@/core/value-object"
+
+interface EmailProps { value: string }
+
+class Email extends ValueObject<EmailProps> {
+  get value() { return this.props.value }
+
+  static create(raw: string): Email {
+    if (!raw.includes("@")) throw new Error("Invalid email")
+    return new Email({ value: raw.toLowerCase() })
+  }
+}
+```
+
+### WatchedList
+
+Track additions and removals in a collection without rewriting the whole thing on save.
+
+```ts
+class TagList extends WatchedList<Tag> {
+  compareItems(a: Tag, b: Tag) { return a.id.equals(b.id) }
+}
+
+const tags = new TagList([existingTag])
+tags.add(newTag)
+tags.remove(existingTag)
+
+tags.getNewItems()     // [newTag]
+tags.getRemovedItems() // [existingTag]
+```
+
+### Domain Events
+
+Events are raised inside aggregates and dispatched by the infrastructure layer after successful persistence.
+
+```ts
+// register a handler
+DomainEvents.register(
+  (event) => sendWelcomeEmail(event as UserCreatedEvent),
+  UserCreatedEvent.name,
+)
+
+// infrastructure dispatches after persisting
+await userRepository.create(user)
+DomainEvents.dispatchEventsForAggregate(user.id)
+```
+
+### Repository Contracts
+
+Repositories are defined as interfaces in the application layer. Implementations live in infrastructure.
+
+```ts
+// application/repositories/user-repository.ts
+export interface UserRepository extends Repository<User> {
+  findByEmail(email: string): Promise<User | null>
+}
+
+// or compose only what you need
+export interface AuditRepository extends Creatable<AuditLog> {}
+```
+
+## Getting Started
+
+```bash
+bun install
+bun test
+```
+
+## Tech
+
+- [Bun](https://bun.sh) — runtime, bundler, and test runner
+- TypeScript 5 with strict mode
+- Zero runtime dependencies
+
+## License
+
+MIT

package/dist/core/index.d.ts

@@ -0,0 +1,270 @@
+/**
+* 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;
+}
+export { right, left, WatchedList, ValueObject, UniqueEntityId, Optional, Either };

package/dist/core/index.js

@@ -0,0 +1,122 @@
+// @bun
+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,
+  WatchedList,
+  ValueObject,
+  UniqueEntityId
+};