clean-architecture-kernel 1.0.0

package/Readme.md

@@ -0,0 +1,224 @@
+# Clean Architecture Kernel
+
+> A lightweight, zero-dependency npm package for implementing Clean Architecture, Domain-Driven Design, and CQRS patterns in Node.js applications.
+
+[![npm version](https://img.shields.io/npm/v/clean-architecture-kernel.svg)](https://www.npmjs.com/package/clean-architecture-kernel)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/built%20with-TypeScript-blue)](https://www.typescriptlang.org/)
+[![Framework Agnostic](https://img.shields.io/badge/framework-agnostic-brightgreen)](https://www.typescriptlang.org/)
+
+## Overview
+## Overview
+
+Clean Architecture Kernel provides the essential building blocks for implementing Clean Architecture, Domain-Driven Design (DDD), and CQRS patterns in your application.
+
+### Why Clean Architecture Kernel?
+
+This package focuses on core domain patterns only, ensuring the kernel remains:
+
+- **Small** - Minimal footprint, zero external dependencies
+- **Fast** - No abstractions, direct pattern implementations  
+- **Framework-agnostic** - Works with any Node.js framework or runtime
+- **Type-safe** - Built with TypeScript for complete type safety
+
+### Universal Primitives
+
+- `Result<T>` - Functional success/failure wrapper
+- `Entity` - Domain entities with identity and events
+- `AggregateRoot` - Aggregate consistency boundaries
+- `ValueObject` - Immutable property-defined objects
+- `DomainEvent` - Domain occurrence representations
+- `Mediator` - In-memory command/query dispatcher
+
+### Perfect For
+
+- Backend services & REST APIs
+- Microservices architectures
+- Serverless functions
+- Monolithic applications
+- Event-driven systems
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Core Concepts](#core-concepts)
+- [Usage Examples](#usage-examples)
+- [Project Structure](#project-structure)
+- [Design Principles](#design-principles)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+Choose your Node.js package manager:
+
+### NPM
+
+```bash
+npm install clean-architecture-kernel
+```
+
+### Yarn
+
+```bash
+yarn add clean-architecture-kernel
+```
+
+### PNPM
+
+```bash
+pnpm add clean-architecture-kernel
+```
+
+## Core Concepts
+## Core Concepts
+
+### Result<T>
+
+A functional wrapper that encapsulates success or failure states, eliminating the need for try-catch blocks.
+
+```typescript
+const result = Result.ok(user);
+
+if (result.isFailure) {
+    console.log(result.error);
+}
+```
+
+### Entity
+
+Base class for domain entities with identity and domain event support.
+
+### AggregateRoot
+
+Specialized entity that acts as a consistency boundary for related entities.
+
+### ValueObject
+
+Immutable object defined by its properties rather than identity, ensuring data integrity.
+
+### DomainEvent
+
+Represents something that happened inside the domain, enabling event-driven architectures.
+
+### Mediator
+
+Simple in-memory mediator pattern for dispatching commands and queries.
+
+## Project Structure
+## Project Structure
+
+```
+src/
+ ├── core/
+ │   ├── Result.ts          # Success/failure wrapper
+ │   ├── Entity.ts          # Domain entity base class
+ │   ├── AggregateRoot.ts   # Aggregate consistency boundary
+ │   ├── ValueObject.ts     # Immutable value object
+ │   ├── DomainEvent.ts     # Domain event base class
+ │   └── Mediator.ts        # Command/query dispatcher
+ └── index.ts               # Public API exports
+```
+
+## Usage Examples
+
+### 1. Creating a Value Object
+
+```typescript
+class Email extends ValueObject<{ value: string }> {
+    private constructor(props) {
+        super(props);
+    }
+
+    static create(value: string): Result<Email> {
+        if (!value.includes("@")) {
+            return Result.fail("Invalid email");
+        }
+        return Result.ok(new Email({ value }));
+    }
+}
+```
+
+### 2. Creating an Entity
+
+```typescript
+class User extends AggregateRoot<string> {
+    constructor(id: string, public email: Email) {
+        super(id);
+    }
+}
+```
+
+### 3. Defining a Command
+
+```typescript
+class CreateUserCommand {
+    constructor(public readonly email: string) {}
+}
+```
+
+### 4. Implementing a Command Handler
+
+```typescript
+class CreateUserHandler {
+    async handle(command: CreateUserCommand) {
+        const emailResult = Email.create(command.email);
+        if (emailResult.isFailure) return emailResult;
+
+        const user = new User("123", emailResult.value);
+        return Result.ok(user);
+    }
+}
+```
+
+### 5. Using the Mediator
+
+```typescript
+const mediator = new Mediator();
+mediator.register("CreateUserCommand", new CreateUserHandler());
+
+const result = await mediator.send(new CreateUserCommand("test@mail.com"));
+```
+
+## Design Principles
+## Design Principles
+
+✓ **No Dependencies** - Pure TypeScript/JavaScript, zero external npm packages  
+✓ **Predictable Behavior** - Consistent, deterministic pattern implementations  
+✓ **Production-Ready** - Optimized for Node.js backends and microservices  
+✓ **Minimal API** - Small surface area, easy to learn and understand  
+✓ **Type-Safe** - Full TypeScript support out of the box  
+✓ **Inspired by** - Domain-Driven Design, Clean Architecture, and CQRS
+
+## Roadmap
+
+- [ ] Event Bus abstraction for decoupled event publishing
+- [ ] Notification pattern implementation
+- [ ] Pipeline behaviors (logging, validation, metrics)
+- [ ] Async domain event dispatcher
+- [ ] Optional integrations (Redis, Kafka, RabbitMQ)
+- [ ] Advanced aggregate query patterns
+- [ ] Built-in validation framework
+
+## Contributing
+
+Contributions are welcome! To contribute:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+Please ensure your code follows the existing style and includes appropriate tests.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+**Made with ❤️ by Andrés Mariño**
+
+*For developers building scalable, maintainable architectures*

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "clean-architecture-kernel",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module"
+}

package/src/core/AggregateRoot.ts

@@ -0,0 +1,3 @@
+import { Entity } from "./Entity";
+
+export abstract class AggregateRoot<TId> extends Entity<TId> {}

package/src/core/DomainEvent.ts

@@ -0,0 +1,4 @@
+export abstract class DomainEvent {
+    public readonly occurredOn: Date = new Date();
+    abstract eventName(): string;
+}

package/src/core/Entity.ts

@@ -0,0 +1,19 @@
+import { DomainEvent } from "./DomainEvent";
+
+export abstract class Entity<TId> {
+    private _domainEvents: DomainEvent[] = [];
+
+    constructor(public readonly id: TId) {}
+
+    get domainEvents(): DomainEvent[] {
+        return this._domainEvents;
+    }
+
+    protected addDomainEvent(event: DomainEvent): void {
+        this._domainEvents.push(event);
+    }
+
+    public clearEvents(): void {
+        this._domainEvents = [];
+    }
+}

package/src/core/Mediator.ts

@@ -0,0 +1,13 @@
+export class Mediator {
+    private handlers = new Map();
+
+    register(commandType: string, handler: any) {
+        this.handlers.set(commandType, handler);
+    }
+
+    async send(command: any) {
+        const handler = this.handlers.get(command.constructor.name);
+        if (!handler) throw new Error(`No handler for ${command.constructor.name}`);
+        return handler.handle(command);
+    }
+}

package/src/core/Result.ts

@@ -0,0 +1,29 @@
+export class Result<T> {
+    private constructor(
+        public readonly isSuccess: boolean,
+        public readonly error?: string,
+        private readonly _value?: T
+    ) {
+        if (isSuccess && error) {
+            throw new Error("A result cannot be successful and contain an error");
+        }
+        if (!isSuccess && !error) {
+            throw new Error("A failing result needs an error message");
+        }
+    }
+
+    get value(): T {
+        if (!this.isSuccess) {
+            throw new Error("Cannot get value of a failed result");
+        }
+        return this._value as T;
+    }
+
+    static ok<U>(value?: U): Result<U> {
+        return new Result<U>(true, undefined, value);
+    }
+
+    static fail<U>(error: string): Result<U> {
+        return new Result<U>(false, error);
+    }
+}

package/src/core/ValueObject.ts

@@ -0,0 +1,7 @@
+export abstract class ValueObject<TProps> {
+    constructor(public readonly props: TProps) {}
+
+    equals(vo: ValueObject<TProps>): boolean {
+        return JSON.stringify(this.props) === JSON.stringify(vo.props);
+    }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./core/Result";
+export * from "./core/DomainEvent";
+export * from "./core/Entity";
+export * from "./core/AggregateRoot";
+export * from "./core/ValueObject";
+export * from "./core/Mediator";