tshex-cli 1.0.19 → 1.0.21

package/docs/shared/application/events.md

@@ -0,0 +1,144 @@
+### Events
+
+Events represent something that occurred in the application.
+They are used to make side effects explicit and to separate the main process
+from the reactions that can happen after that process completes.
+
+The generated template defines three contracts: `Event`, `EventHandler`, and
+`EventDispatcher`.
+
+#### Event
+
+`Event` is responsible for carrying the event time and its plain details.
+
+```ts title="shared/application/events.ts"
+export abstract class Event {
+	public constructor(
+		public readonly timestamp: number = Date.now(),
+		public readonly details: Record<string, unknown> = {},
+	) {}
+}
+```
+
+Every event instance includes a timestamp and a `details` object. Concrete
+events can extend this base class directly when the generic `details` payload is
+enough for the process.
+
+#### First Event
+
+In the following example we define an event for user registration.
+
+```ts title="users/application/user-registered.ts"
+import { Event } from '../../shared/application/events.js'
+
+export class UserRegisteredEvent extends Event {}
+
+const event = new UserRegisteredEvent(Date.now(), {
+	userId: 'usr_1',
+	email: 'ada@example.com',
+})
+```
+
+`UserRegisteredEvent` does not need additional code because the generated base
+class already stores the time and the details.
+
+#### Event Handler
+
+`EventHandler` is responsible for reacting to an event.
+
+```ts title="shared/application/events.ts"
+export abstract class EventHandler {
+	public abstract handle(event: Event): Promise<void>
+}
+```
+
+Now that the event exists, a handler can implement the required `handle()`
+method.
+
+```ts title="users/adapters/send-welcome-email.ts"
+import { Event, EventHandler } from '../../shared/application/events.js'
+
+export class SendWelcomeEmailHandler extends EventHandler {
+	public async handle(event: Event): Promise<void> {
+		const email = String(event.details.email)
+		void email
+	}
+}
+```
+
+This example keeps the reaction minimal. In a real adapter, the handler would
+call an email provider or another external system.
+
+#### Event Dispatcher
+
+`EventDispatcher` is responsible for subscription management and event
+publication.
+
+```ts title="shared/application/events.ts"
+export abstract class EventDispatcher {
+	public abstract subscribe(key: unknown, handler: EventHandler): void
+
+	public abstract unsubscribe(key: unknown, handler: EventHandler): void
+
+	public abstract dispatch(event: Event): void
+}
+```
+
+In the following example we use an in-memory dispatcher.
+
+```ts title="users/adapters/in-memory-dispatcher.ts"
+import {
+	Event,
+	EventDispatcher,
+	EventHandler,
+} from '../../shared/application/events.js'
+
+export class InMemoryDispatcher extends EventDispatcher {
+	private readonly handlers = new Map<string, Array<EventHandler>>()
+
+	public subscribe(key: unknown, handler: EventHandler): void {
+		const normalizedKey = String(key)
+		const existing = this.handlers.get(normalizedKey) ?? []
+		this.handlers.set(normalizedKey, [...existing, handler])
+	}
+
+	public unsubscribe(key: unknown, handler: EventHandler): void {
+		const normalizedKey = String(key)
+		const existing = this.handlers.get(normalizedKey) ?? []
+		this.handlers.set(
+			normalizedKey,
+			existing.filter((current) => current !== handler),
+		)
+	}
+
+	public dispatch(event: Event): void {
+		const key = event.constructor.name
+		const handlers = this.handlers.get(key) ?? []
+
+		for (const handler of handlers) {
+			void handler.handle(event)
+		}
+	}
+}
+```
+
+The dispatcher keeps the subscription mechanics outside the application service.
+This allows the service to publish an event without knowing how reactions are
+registered or executed.
+
+> **Warning**
+> The generated dispatcher contract does not define durability, retries, or
+> ordering guarantees. If the application needs those guarantees, document and
+> implement them in the concrete adapter.
+
+#### Example Flow
+
+The normal flow is the following:
+
+```text
+service -> dispatch(event)
+dispatcher -> matching handlers
+handlers -> side effects
+```
+
+This keeps the main process separate from secondary reactions.

package/docs/shared/application/http.md

@@ -0,0 +1,131 @@
+### HTTP
+
+The HTTP contracts define a transport-facing boundary without coupling the
+generated structure to a specific framework.
+They are used when an adapter needs to describe requests, responses, handlers,
+or middleware in a consistent way.
+
+The generated template keeps `HttpRequest` and `HttpResponse` empty on purpose.
+Each project can extend them with the fields required by its own transport.
+
+#### Response Body
+
+`HttpResponseBody` is responsible for standardizing the shape of the response
+payload.
+
+```ts title="shared/application/http.ts"
+export interface HttpResponseBody {
+    readonly data: Record<string, unknown> | null
+    readonly errors: string[] | null
+    readonly links: Record<string, URL> | null
+}
+```
+
+This structure makes successful data, error messages, and related links
+explicit without forcing a specific router or server implementation.
+
+#### Request Handler
+
+`HttpRequestHandler` is responsible for processing a request and returning a
+response.
+
+```ts title="shared/application/http.ts"
+export interface HttpRequestHandler {
+    handle(request: HttpRequest): HttpResponse | Promise<HttpResponse>
+}
+```
+
+In the following example we define adapter-specific request and response types,
+then implement a handler.
+
+```ts title="users/adapters/get-user-handler.ts"
+import {
+    HttpRequest,
+    HttpRequestHandler,
+    HttpResponse,
+    HttpResponseBody,
+} from '../../shared/application/http.js'
+
+interface UserHttpRequest extends HttpRequest {
+    readonly params: {
+        id: string
+    }
+}
+
+interface UserHttpResponse extends HttpResponse {
+    readonly status: number
+    readonly body: HttpResponseBody
+}
+
+export class GetUserHandler implements HttpRequestHandler {
+    public handle(request: HttpRequest): HttpResponse {
+        const typedRequest = request as UserHttpRequest
+
+        return {
+            status: 200,
+            body: {
+                data: {
+                    id: typedRequest.params.id,
+                },
+                errors: null,
+                links: null,
+            },
+        } as UserHttpResponse
+    }
+}
+```
+
+The generated `HttpRequest` and `HttpResponse` interfaces stay empty, so the
+adapter declares the transport-specific fields locally. This keeps the shared
+contract small and portable.
+
+#### Middleware
+
+`HttpMiddleware` is responsible for running logic before or around the handler.
+
+```ts title="shared/application/http.ts"
+export interface HttpMiddleware {
+    process(
+        request: HttpRequest,
+        handler: HttpRequestHandler,
+    ): HttpResponse | Promise<HttpResponse>
+}
+```
+
+Now that the handler exists, middleware can wrap it.
+
+```ts title="users/adapters/request-logger.ts"
+import {
+    HttpMiddleware,
+    HttpRequest,
+    HttpRequestHandler,
+    HttpResponse,
+} from '../../shared/application/http.js'
+
+export class RequestLoggerMiddleware implements HttpMiddleware {
+    public async process(
+        request: HttpRequest,
+        handler: HttpRequestHandler,
+    ): Promise<HttpResponse> {
+        void request
+        return handler.handle(request)
+    }
+}
+```
+
+This middleware does not mutate the request or response. It only shows where
+cross-cutting behavior belongs in the generated HTTP abstraction.
+
+> **Warning**
+> Do not treat the shared HTTP contracts as a full framework abstraction. They
+> only define the minimum boundary for adapters. Routing, serialization, and
+> status code policies remain the responsibility of the concrete transport.
+
+#### Example Flow
+
+```text
+request -> middleware -> handler -> response body
+```
+
+This flow keeps the transport boundary explicit while leaving framework choices
+to the adapter layer.

package/docs/shared/application/loggers.md

@@ -0,0 +1,127 @@
+### Loggers
+
+The logging contracts define how the application layer emits operational
+information.
+They are used to keep services independent from a concrete logging library or
+transport.
+
+The generated template provides shared level constants and the abstract
+`Logger` contract.
+
+#### Log Levels
+
+The following constants describe the generated severity scale.
+
+| Constant | Value |
+| --- | --- |
+| `DEBUG` | `10` |
+| `INFO` | `20` |
+| `WARNING` | `30` |
+| `ERROR` | `40` |
+| `CRITICAL` | `50` |
+
+These values give the project a shared vocabulary for severity without forcing
+any adapter to use a particular logger implementation.
+
+#### Logger
+
+`Logger` is responsible for receiving log data from the application layer.
+
+```ts title="shared/application/loggers.ts"
+export abstract class Logger {
+	public abstract debug(data: unknown): void
+
+	public abstract info(data: unknown): void
+
+	public abstract warning(data: unknown): void
+
+	public abstract error(data: unknown): void
+
+	public abstract critical(data: unknown): void
+}
+```
+
+The contract is intentionally small. It defines the actions the application can
+request, while the adapter decides how those actions are persisted or displayed.
+
+#### First Adapter
+
+In the following example we implement a console-based logger.
+
+```ts title="users/adapters/console-logger.ts"
+import { Logger } from '../../shared/application/loggers.js'
+
+type ExternalService = {
+    debug(data: unknown): void
+    info(data: unknown): void
+    warning(data: unknown): void
+    error(data: unknown): void
+    critical(data: unknown): void
+}
+
+export class ConsoleLogger extends Logger {
+    constructor(protected readonly externalService: ExternalService) {
+        super()
+    }
+
+	public debug(data: unknown): void {
+		this.externalService.debug(data)
+	}
+
+	public info(data: unknown): void {
+		this.externalService.info(data)
+	}
+
+	public warning(data: unknown): void {
+		this.externalService.warning(data)
+	}
+
+	public error(data: unknown): void {
+		this.externalService.error(data)
+	}
+
+	public critical(data: unknown): void {
+		this.externalService.critical(data)
+	}
+}
+```
+
+This adapter satisfies the generated contract without changing the application
+layer.
+
+#### Service Integration
+
+Now that the logger exists, an application service can depend on the contract.
+
+```ts title="users/application/register-user.ts"
+import { Service } from '../../shared/application/services.js'
+import { Logger } from '../../shared/application/loggers.js'
+
+export class RegisterUser extends Service {
+	public constructor(private readonly logger: Logger) {
+		super()
+	}
+
+	public async execute(email: string): Promise<void> {
+		this.logger.info({
+			message: 'Registering user',
+			email,
+		})
+	}
+}
+```
+
+The service does not know whether the logger writes to the console, a file, or
+an external platform. It only depends on the application-level contract.
+
+> **Hint**
+> Pass structured objects when the project needs machine-readable logs. The
+> generated contract accepts `unknown`, so the adapter can enforce its own shape.
+
+#### Example Flow
+
+```text
+service -> Logger contract -> adapter -> logging backend
+```
+
+This flow keeps observability concerns outside the core process.

package/docs/shared/application/services.md

@@ -0,0 +1,120 @@
+### Services
+
+An application service is responsible for coordinating domain capabilities and
+collaborators to fulfill a system purpose.
+It defines the process of a use case, not the business meaning of the domain
+objects involved in that use case.
+
+The generated template provides `Service` as a semantic base class for these
+processes.
+
+#### Base Class
+
+`Service` is an abstract class with no concrete behavior.
+
+```ts title="shared/application/services.ts"
+export abstract class Service {}
+```
+
+This design is intentional. The generated class marks the role of the object
+without imposing an `execute()` method, a result shape, or a framework-specific
+lifecycle.
+
+#### First Service
+
+In the following example we build a small registration process.
+
+```ts title="users/application/register-user.ts"
+import { Service } from '../../shared/application/services.js'
+import { Email, NullableBoolean } from '../../shared/domain/value-objects.js'
+
+type UserRecord = {
+	id: string
+	email: string
+	active: boolean | null
+}
+
+type SaveUser = {
+	save(user: UserRecord): Promise<UserRecord>
+}
+
+export class RegisterUser extends Service {
+	public constructor(private readonly repository: SaveUser) {
+		super()
+	}
+
+	public async execute(data: {
+		id: string
+		email: string
+		active: boolean | null
+	}): Promise<UserRecord> {
+		const email = Email.from(data.email)
+		const active = NullableBoolean.from(data.active)
+
+		return this.repository.save({
+			id: data.id,
+			email: email.value,
+			active: active.value,
+		})
+	}
+}
+```
+
+The service coordinates the process. It validates the email, normalizes the
+tri-state boolean, and delegates persistence to a collaborator.
+
+The service does not own the email validation rule or the repository transport.
+Those concerns remain in the value object and the adapter-facing collaborator.
+
+#### Validation Failures
+
+Now consider a process that wants to return an explicit result when the input
+cannot be converted into domain objects.
+
+```ts title="users/application/register-user.ts"
+import { Service } from '../../shared/application/services.js'
+import { Email } from '../../shared/domain/value-objects.js'
+import { ValueError } from '../../shared/domain/errors.js'
+
+type RegistrationResult =
+	| { ok: true; email: string }
+	| { ok: false; error: string }
+
+export class RegisterUserSafely extends Service {
+	public execute(email: string): RegistrationResult {
+		try {
+			return {
+				ok: true,
+				email: Email.from(email).value,
+			}
+		} catch (error: unknown) {
+			if (error instanceof ValueError) {
+				return {
+					ok: false,
+					error: error.message,
+				}
+			}
+
+			throw error
+		}
+	}
+}
+```
+
+`Email.from()` throws `ValueError` when the input is invalid. The service can
+either allow that error to propagate or translate it into an application-level
+result, depending on the requirements of the use case.
+
+> **Warning**
+> `Service` does not guarantee a method name or a result contract. If the codebase
+> needs those conventions, establish them explicitly in project code instead of
+> assuming the generated base class already provides them.
+
+#### Example Flow
+
+```text
+input -> service -> domain capabilities -> collaborators -> result
+```
+
+This flow keeps orchestration in the application layer and domain meaning in
+the domain layer.

package/docs/shared/application/validations.md

@@ -0,0 +1,94 @@
+### Validations
+
+Validation objects are responsible for checking whether application input is
+ready for the next step of a process.
+They are used to keep validation explicit before the application constructs
+domain objects or invokes external collaborators.
+
+The generated template provides a single contract for this purpose:
+`Validatable`.
+
+#### Contract
+
+`Validatable` is responsible for exposing a Boolean validation result.
+
+```ts title="shared/application/validations.ts"
+export interface Validatable {
+	isValid(): boolean
+}
+```
+
+This contract stays deliberately small. It does not prescribe how errors are
+stored, how messages are formatted, or whether validation is synchronous or
+composed from several objects.
+
+#### First Validation Object
+
+In the following example we validate a registration payload before the service
+turns it into domain values.
+
+```ts title="users/application/create-user-input.ts"
+import { Validatable } from '../../shared/application/validations.js'
+import { Email } from '../../shared/domain/value-objects.js'
+
+export class CreateUserInput implements Validatable {
+	public constructor(
+		public readonly id: string,
+		public readonly email: string,
+	) {}
+
+	public isValid(): boolean {
+		return this.id.length > 0 && Email.isValid(this.email)
+	}
+}
+```
+
+`CreateUserInput` performs application-level checks without constructing an
+`Email` instance yet. This is useful when the process wants to reject invalid
+input before attempting a full domain conversion.
+
+#### Integration With A Service
+
+Now that the validation object exists, a service can decide what to do when the
+input does not satisfy the contract.
+
+```ts title="users/application/register-user.ts"
+import { Service } from '../../shared/application/services.js'
+import { Validatable } from '../../shared/application/validations.js'
+
+type CreateUserInput = Validatable & {
+	readonly id: string
+	readonly email: string
+}
+
+type RegistrationResult =
+	| { ok: true }
+	| { ok: false; errors: string[] }
+
+export class RegisterUser extends Service {
+	public execute(input: CreateUserInput): RegistrationResult {
+		if (input.isValid() === false) {
+			return {
+				ok: false,
+				errors: ['The registration input is invalid.'],
+			}
+		}
+
+		return {
+			ok: true,
+		}
+	}
+}
+```
+
+The service decides the process outcome, while the validation object owns the
+question of whether the input is acceptable.
+
+> **Hint**
+> `Validatable` does not replace domain rules. Use it for application-level
+> checks. Keep domain invariants inside value objects, entities, or aggregates.
+
+#### Next Step
+
+After validation succeeds, the next step is usually to construct domain objects
+or call a repository through an application service.

package/docs/shared/domain/aggregates.md

@@ -0,0 +1,79 @@
+### Aggregates
+
+An aggregate is responsible for grouping multiple entities into one logical
+domain unit.
+It is used when the behavior of the concept depends on the collaboration of
+several entities instead of a single entity in isolation.
+
+The generated template provides `Aggregate` as a semantic base class.
+
+#### Base Class
+
+`Aggregate` is an abstract class with no concrete methods.
+
+```ts title="shared/domain/aggregates.ts"
+export abstract class Aggregate {}
+```
+
+This means the generated base class does not impose persistence rules, event
+publication, or identity behavior. Those concerns remain in the concrete domain
+model of the project.
+
+#### First Aggregate
+
+In the following example we model a shopping cart as a group of line items.
+
+```ts title="users/domain/cart.ts"
+import { Aggregate } from '../../shared/domain/aggregates.js'
+import { Entity } from '../../shared/domain/entities.js'
+
+class LineItem extends Entity {
+	public constructor(
+		public readonly id: string,
+		public readonly quantity: number,
+	) {
+		super()
+	}
+
+	public equals(other: Entity): boolean {
+		return other instanceof LineItem && this.id === other.id
+	}
+}
+
+export class Cart extends Aggregate {
+	public constructor(public readonly items: Array<LineItem>) {
+		super()
+	}
+
+	public totalItems(): number {
+		return this.items.reduce((sum, item) => sum + item.quantity, 0)
+	}
+}
+```
+
+`Cart` is an aggregate because its behavior depends on the collection of
+entities that compose it. `LineItem` remains an entity because its identity is
+independent inside the aggregate.
+
+#### Responsibility Boundary
+
+An aggregate should own rules that require several internal parts to work
+together.
+
+Examples include:
+
+1. checking whether the aggregate can change status;
+2. keeping related entities in a consistent state;
+3. exposing operations that depend on the collaboration of those entities.
+
+The generated `Aggregate` base class does not implement these rules for you. It
+only provides the semantic place where those rules belong.
+
+> **Warning**
+> Do not extend `Aggregate` only to create a container for unrelated values. Use
+> it when the concept represents one domain unit composed of several parts.
+
+#### Next Step
+
+Aggregates usually collaborate with entities and value objects. The base entity
+behavior is documented in `entities.md`.