tshex-cli 1.0.20 → 1.0.21

package/docs/shared/application/data.md

@@ -0,0 +1,185 @@
+### Data
+
+The data contracts define how the application layer interacts with plain source
+records.
+They separate connection management, raw record access, and domain
+transformation so that a context can change drivers without rewriting its use
+cases.
+
+The generated structure splits this concern into three files:
+
+1. `drivers.ts` for connection adapters;
+2. `managers.ts` for plain-record operations;
+3. `repositories.ts` for record-to-domain transformation.
+
+#### Driver Adapter
+
+`DriverAdapter` is responsible for connecting to a data source and returning an
+enabled `DataManager`.
+
+```ts title="shared/application/data/drivers.ts"
+import { DataManager } from './managers.js'
+
+export abstract class DriverAdapter<M extends DataManager = DataManager> {
+    public abstract connect(...args: unknown[]): Promise<M>
+
+    public abstract disconnect(): Promise<unknown>
+}
+```
+
+The `connect()` method returns a manager that can read or manipulate raw data.
+The `disconnect()` method closes the interaction when the work is finished.
+
+#### Data Manager
+
+`DataManager` is responsible for exposing plain source data.
+
+```ts title="shared/application/data/managers.ts"
+export abstract class DataManager<T = Record<string, unknown>> {
+    public none(): Array<T> {
+        return []
+    }
+
+    public abstract all(): Promise<Array<T>>
+}
+```
+
+The base class provides `none()` as an explicit empty result and requires
+`all()` for retrieving records. The generated template also includes operation
+contracts such as `Filterable`, `Creatable`, and `Updatable`, plus the
+`DatasetManager` extension for set operations.
+
+#### First Implementation
+
+In the following example we implement an in-memory manager and its driver.
+
+```ts title="users/adapters/memory-users-driver.ts"
+import { DriverAdapter } from '../../shared/application/data/drivers.js'
+import { DataManager } from '../../shared/application/data/managers.js'
+
+type UserRecord = {
+    id: string
+    email: string
+    active: boolean | null
+}
+
+class MemoryUsersManager extends DataManager<UserRecord> {
+    public constructor(private readonly rows: Array<UserRecord>) {
+        super()
+    }
+
+    public async all(): Promise<Array<UserRecord>> {
+        return this.rows
+    }
+}
+
+export class MemoryUsersDriver extends DriverAdapter<MemoryUsersManager> {
+    public constructor(private readonly rows: Array<UserRecord>) {
+        super()
+    }
+
+    public async connect(): Promise<MemoryUsersManager> {
+        return new MemoryUsersManager(this.rows)
+    }
+
+    public async disconnect(): Promise<void> {
+        return undefined
+    }
+}
+```
+
+`MemoryUsersDriver` owns the connection contract. `MemoryUsersManager` owns the
+raw records. The application layer can use both without knowing whether the
+source is memory, SQL, or an HTTP-backed adapter.
+
+#### Repository
+
+`Repository` is responsible for transforming raw records into domain-oriented
+representations.
+
+```ts title="shared/application/data/repositories.ts"
+import { type DataManager } from './managers.js'
+import { type DriverAdapter } from './drivers.js'
+
+export abstract class Repository<
+    DataShape extends Record<string, unknown> = Record<string, unknown>,
+    EntityShape extends Record<string, unknown> = Record<string, unknown>
+> {
+    public constructor(public readonly driver: DriverAdapter<DataManager<DataShape>>) {}
+
+    public async all(): Promise<Array<EntityShape>> {
+        const connection = await this.driver.connect()
+        const raw = await connection.all()
+        const entities = this.transformList(raw)
+        await this.driver.disconnect()
+        return entities
+    }
+
+    protected transformList(data: Array<DataShape>): Array<EntityShape> {
+        return data.map(this.transform)
+    }
+
+    protected abstract transform(data: DataShape): EntityShape
+}
+```
+
+The base repository already defines the `all()` flow. A concrete repository only
+needs to implement `transform()`.
+
+#### Repository Implementation
+
+Now that the driver exists, a repository can translate raw records into a shape
+that the rest of the context can use.
+
+```ts title="users/adapters/users-repository.ts"
+import { Repository } from '../../shared/application/data/repositories.js'
+import { DriverAdapter } from '../../shared/application/data/drivers.js'
+import { DataManager } from '../../shared/application/data/managers.js'
+
+type UserRecord = {
+    id: string
+    email: string
+    active: boolean | null
+}
+
+type UserView = {
+    id: string
+    email: string
+    active: boolean | null
+}
+
+export class UsersRepository extends Repository<UserRecord, UserView> {
+    public constructor(driver: DriverAdapter<DataManager<UserRecord>>) {
+        super(driver)
+    }
+
+    protected transform(data: UserRecord): UserView {
+        return {
+            id: data.id,
+            email: data.email,
+            active: data.active,
+        }
+    }
+}
+```
+
+This repository does not own the connection lifecycle because `Repository`
+already handles it. Its responsibility is the mapping between raw source data
+and the representation used by the context.
+
+> **Warning**
+> The generated `Repository` only implements `all()`. If the project needs
+> filtering, creation, or updates, add those operations explicitly instead of
+> assuming they already exist in the base class.
+
+#### Example Flow
+
+The normal flow of the data abstractions is the following:
+
+```text
+service -> repository -> driver -> data manager -> raw records
+service <- repository <- transformed records
+```
+
+This separation keeps the application service focused on orchestration while
+the repository focuses on transformation.

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.