tshex-cli 1.0.18 → 1.0.19

package/README.md

@@ -2,7 +2,7 @@
 
 `tshex-cli` creates the base structure of a library organized by contexts. The structure groups shared contracts, domain concepts, use cases, and adapters into directories with defined responsibilities.
 
-In this guide, we will build a library named `core` with a context named `users`. The walkthrough starts with the CLI and continues with the implementation of each generated component.
+In this guide, we will build a library named `core` with a context named `users`. The walkthrough starts with the CLI and then explains the purpose of the generated components.
 
 The examples in this guide are intentionally simple. They are designed to show the responsibility of each component, not to cover real infrastructure or production scenarios.
 
@@ -74,7 +74,10 @@ core/
 ├── main.ts
 ├── shared/
 │   ├── application/
-│   │   ├── data-sources.ts
+│   │   ├── data/
+│   │   │   ├── drivers.ts
+│   │   │   ├── managers.ts
+│   │   │   └── repositories.ts
 │   │   ├── events.ts
 │   │   ├── http.ts
 │   │   ├── loggers.ts
@@ -89,8 +92,7 @@ core/
     ├── adapters/
     ├── application/
     ├── domain/
-    ├── example-ports.ts
-    └── index.ts
+    └── example-ports.ts
 ```
 
 ### Choose the destination directory
@@ -146,7 +148,7 @@ The library is divided into a root, a shared directory, and one or more contexts
 
 The root contains `index.d.ts` and `main.ts`.
 
-`index.d.ts` declares the types available to the library. `main.ts` contains the main implementation and the public components that belong directly to that entry point.
+`index.d.ts` declares the types available to the library. `main.ts` starts as a placeholder for the main implementation and the public components that belong directly to that entry point.
 
 ### Shared code
 
@@ -195,7 +197,7 @@ An application service combines capabilities to complete an operation. For examp
 
 #### Context root
 
-The root contains `index.ts` and other `.ts` files intended for the context's ports.
+The generated context root contains `example-ports.ts` as a starting point for the context's ports. You can keep that file, replace it, or add `index.ts` and other `.ts` files at the context root as the communication surface grows.
 
 A port describes a form of communication between the context and another system. It defines the received data, the returned data, and the operation available at that boundary.
 
@@ -225,7 +227,7 @@ The application occupies the middle layer and uses those capabilities to build p
 
 Ports and adapters occupy the outer layer and handle communication between systems.
 
-A port declares the communication available at the context boundary: what data enters, what data leaves, and which operation is exposed. Ports are declared in `index.ts` or in `.ts` modules located at the context root.
+A port declares the communication available at the context boundary: what data enters, what data leaves, and which operation is exposed. Ports are declared in `.ts` modules located at the context root. Many projects centralize them in `index.ts`, but the generated template starts with `example-ports.ts`.
 
 An adapter implements that communication. It imports the corresponding port, translates external input or output into the application process format, and delegates the work to the application service.
 
@@ -237,7 +239,7 @@ adapter → application
 application → domain
 ```
 
-For example, `users/index.ts` declares the `CreateUserPort` port. `users/adapters/create-user-adapter.ts` imports that port and connects an external request to `users/application/create-user-service.ts`. The service applies the capabilities of `Email` and `User` to complete the registration.
+One possible arrangement is to keep `users/example-ports.ts` at the context root and replace the starter export with your own contracts as the context grows. In this guide, the examples stay close to the generated files: value objects extend `ValueObject`, entities extend `Entity`, services extend `Service`, repositories extend `Repository`, and ports live at the context root.
 
 > **Tip:** start the implementation inside the context and move a component to `shared` when its meaning and use belong to multiple contexts.
 
@@ -286,16 +288,17 @@ The `shared/domain/value-objects.ts` file generates the `ValueObject<T>` base cl
 ```ts
 import { Email } from './core/shared/domain/value-objects.js'
 
-const email = Email.from('alejandro@example.com')
+const email = Email.from('ana@example.com')
 
 email.value
+email.username
 email.domain
 ```
 
 Creation is performed with `Email.from()`. This method runs `Email.isValid()` before constructing the instance.
 
 ```ts
-Email.isValid('alejandro@example.com')
+Email.isValid('ana@example.com')
 ```
 
 Every creation follows the same validity rule:
@@ -321,53 +324,53 @@ When validation fails, `from()` throws `ValueError`.
 ```ts
 import { NullableBoolean } from './core/shared/domain/value-objects.js'
 
-const status = NullableBoolean.from(null)
+const active = NullableBoolean.from(null)
 
-status.value
-status.isIndeterminate()
+active.value
+active.isIndeterminate()
 ```
 
 The `isIndeterminate()` method expresses an operation specific to the concept and allows the `null` state to be checked with explicit intent.
 
 #### Implement a value object
 
-We will create a discount percentage. The example has only one rule and one operation so the focus remains on the value object concept.
-
-**`sales/domain/discount-percentage.ts`**
+We will create a user name. The example has one rule and one small operation so the focus stays on the value object itself.
 
 ```ts
 import { ValueError } from '../../shared/domain/errors.js'
 import { ValueObject } from '../../shared/domain/value-objects.js'
 
-export class DiscountPercentage extends ValueObject<number> {
-    public override readonly value: number
+export class UserName extends ValueObject<string> {
+    public override readonly value: string
 
-    protected constructor(value: number) {
+    protected constructor(value: string) {
         super()
         this.value = value
     }
 
     public override equals(
-        other: DiscountPercentage | null | undefined
+        other: UserName | null | undefined
     ): boolean {
-        return other instanceof DiscountPercentage &&
+        return other instanceof UserName &&
             this.value === other.value
     }
 
-    public applyTo(amount: number): number {
-        return amount - amount * (this.value / 100)
+    public normalized(): string {
+        return this.value.trim().toLowerCase()
     }
 
     public static override isValid(value: unknown): boolean {
-        return typeof value === 'number' &&
-            Number.isFinite(value) &&
-            value >= 0 &&
-            value <= 100
+        if (super.isValid(value) === false) {
+            return false
+        }
+
+        return typeof value === 'string' &&
+            value.trim().length > 0
     }
 
-    public static from(value: number): DiscountPercentage {
+    public static from(value: string): UserName {
         if (this.isValid(value) === false) {
-            throw new ValueError(String(value), this.name)
+            throw new ValueError(value, this.name)
         }
 
         return new this(value)
@@ -378,21 +381,19 @@ export class DiscountPercentage extends ValueObject<number> {
 Now we can create and use the concept:
 
 ```ts
-const discount = DiscountPercentage.from(15)
-const finalPrice = discount.applyTo(100)
+const name = UserName.from('Ana')
+const normalized = name.normalized()
 ```
 
-`isValid()` centralizes the rule. `from()` creates the valid instance. `applyTo()` adds behavior specific to the concept.
+`isValid()` centralizes the rule. `from()` creates the valid instance. `normalized()` adds behavior specific to the concept.
 
 ### Entities
 
 An entity represents a concept with its own identity. Two instances represent the same element when they share that identity.
 
-The `shared/domain/entities.ts` file generates the `Entity` base class. Each entity implements `equals()` and `toJSON()`.
+The `shared/domain/entities.ts` file generates the `Entity` base class. Each entity implements `equals()`. The inherited `toJSON()` method can be overridden when you want to return a plain object.
 
-We will create an entity for the `users` context.
-
-**`users/domain/user.ts`**
+This example creates an entity for the `users` context.
 
 ```ts
 import { Entity } from '../../shared/domain/entities.js'
@@ -401,9 +402,14 @@ import {
     NullableBoolean
 } from '../../shared/domain/value-objects.js'
 
+type UserName = {
+    value: string
+}
+
 export class User extends Entity {
     public constructor(
         public readonly id: string,
+        public readonly name: UserName,
         public readonly email: Email,
         public readonly active: NullableBoolean
     ) {
@@ -417,6 +423,7 @@ export class User extends Entity {
     public override toJSON(): Record<string, unknown> {
         return {
             id: this.id,
+            name: this.name.value,
             email: this.email.value,
             active: this.active.value
         }
@@ -431,50 +438,48 @@ The `id` property defines the identity. The `equals()` method compares entities
 ```ts
 const user = new User(
     'user-1',
-    Email.from('alejandro@example.com'),
+    UserName.from('Ana'),
+    Email.from('ana@example.com'),
     NullableBoolean.from(true)
 )
 
 const json = user.toJSON()
 ```
 
-The result uses the internal values of `Email` and `NullableBoolean`.
+The result uses the internal values of `UserName`, `Email`, and `NullableBoolean`.
 
 ### Aggregates
 
 An aggregate groups multiple entities into a logical unit. The aggregate's operations depend on all the identities that compose it.
 
-A team can group one leader and several members:
+A user list can group several users:
 
 ```text
-Team
-├── leader
-└── members
+UserList
+└── items
 ```
 
 Each element preserves its own identity within the unit.
 
-**`users/domain/team.ts`**
-
 ```ts
 import { Aggregate } from '../../shared/domain/aggregates.js'
-import type { User } from './user.js'
 
-export class Team extends Aggregate {
-    public constructor(
-        public readonly leader: User,
-        public readonly members: User[]
-    ) {
+type User = {
+    id: string
+}
+
+export class UserList extends Aggregate {
+    public constructor(public readonly items: User[]) {
         super()
     }
 
-    public size(): number {
-        return this.members.length + 1
+    public count(): number {
+        return this.items.length
     }
 }
 ```
 
-`Team` groups multiple `User` entities into a single logical unit. The `size()` method operates on that group.
+`UserList` groups multiple `User` entities into a single logical unit. The `count()` method operates on that group.
 
 ### Domain errors
 
@@ -483,8 +488,8 @@ The `shared/domain/errors.ts` file generates `ValueError`. This error represents
 ```ts
 import { ValueError } from '../../shared/domain/errors.js'
 
-if (quantity <= 0) {
-    throw new ValueError(String(quantity), 'PositiveQuantity')
+if (userId.trim().length === 0) {
+    throw new ValueError(userId, 'UserId')
 }
 ```
 
@@ -500,35 +505,34 @@ The `shared/application/validations.ts` file declares the `Validatable` contract
 
 ```ts
 isValid(): boolean
-validate(): unknown
 ```
 
-`isValid()` checks the validation state. `validate()` performs the validation and returns the result defined by the implementation.
+`isValid()` checks whether the data is valid according to the rule defined by the implementation.
 
 We will create a validation for the use case that registers users.
 
-**`users/application/create-user-validation.ts`**
-
 ```ts
 import type { Validatable } from '../../shared/application/validations.js'
 import { Email } from '../../shared/domain/value-objects.js'
 
+export type CreateUserValidationData = {
+    name: string
+    email: string
+}
+
 export class CreateUserValidation implements Validatable {
-    public constructor(private readonly email: string) {}
+    public constructor(
+        private readonly data: CreateUserValidationData
+    ) {}
 
     public isValid(): boolean {
-        return Email.isValid(this.email)
-    }
-
-    public validate(): string[] {
-        return this.isValid()
-            ? []
-            : ['The email is invalid.']
+        return this.data.name.trim().length > 0 &&
+            Email.isValid(this.data.email)
     }
 }
 ```
 
-The application service can run this validation before constructing the `User` entity.
+In this example, the application service runs this validation before constructing the `User` entity.
 
 ### Services
 
@@ -538,30 +542,59 @@ The `shared/application/services.ts` file generates the `Service` base class. A
 
 We will begin with a service that creates a user.
 
-**`users/application/create-user-service.ts`**
-
 ```ts
+import type { Validatable } from '../../shared/application/validations.js'
 import { Service } from '../../shared/application/services.js'
 import {
     Email,
     NullableBoolean
 } from '../../shared/domain/value-objects.js'
-import { User } from '../domain/user.js'
-import { CreateUserValidation } from './create-user-validation.js'
-
-export interface UserWriter {
-    save(user: User): Promise<void>
-}
 
-export type CreateUserCommand = {
+export type CreateUserData = {
     id: string
+    name: string
     email: string
 }
 
-export type CreatedUser = {
-    id: string
-    email: string
-    active: boolean | null
+export class UserName {
+    public constructor(public readonly value: string) {}
+
+    public static from(value: string): UserName {
+        return new UserName(value.trim())
+    }
+}
+
+export class User {
+    public constructor(
+        public readonly id: string,
+        public readonly name: UserName,
+        public readonly email: Email,
+        public readonly active: NullableBoolean
+    ) {}
+}
+
+export class CreateUserValidation implements Validatable {
+    public constructor(
+        private readonly data: CreateUserData
+    ) {}
+
+    public isValid(): boolean {
+        return this.data.name.trim().length > 0 &&
+            Email.isValid(this.data.email)
+    }
+}
+
+export interface UserWriter {
+    save(data: { user: User }): Promise<void>
+}
+
+export type CreateUserResult = {
+    user: {
+        id: string
+        name: string
+        email: string
+        active: boolean | null
+    }
 }
 
 export class CreateUserService extends Service {
@@ -569,78 +602,102 @@ export class CreateUserService extends Service {
         super()
     }
 
-    public async execute(
-        command: CreateUserCommand
-    ): Promise<CreatedUser> {
-        const validation = new CreateUserValidation(command.email)
-        const errors = validation.validate()
+    public async execute(data: CreateUserData): Promise<CreateUserResult> {
+        const validation = new CreateUserValidation(data)
 
-        if (errors.length !== 0) {
-            throw new Error(errors.join(', '))
+        if (validation.isValid() === false) {
+            throw new Error('The name or email is invalid.')
         }
 
         const user = new User(
-            command.id,
-            Email.from(command.email),
+            data.id,
+            UserName.from(data.name),
+            Email.from(data.email),
             NullableBoolean.from(true)
         )
 
-        await this.users.save(user)
+        await this.users.save({ user })
 
         return {
-            id: user.id,
-            email: user.email.value,
-            active: user.active.value
+            user: {
+                id: user.id,
+                name: user.name.value,
+                email: user.email.value,
+                active: user.active.value
+            }
         }
     }
 }
 ```
 
-The service receives a command, validates the input, constructs the entity, and delegates persistence. `CreateUserCommand` expresses the process input. `CreatedUser` expresses the output.
+In this example, the service receives one object, validates it, constructs the entity, delegates persistence, and returns another object with the result.
 
 ### HTTP responses
 
-The `shared/application/http.ts` file generates `HttpResponseBody`, a response body designed for REST APIs.
+The `shared/application/http.ts` file generates lightweight HTTP contracts: `HttpRequest`, `HttpResponse`, `HttpResponseBody`, `HttpRequestHandler`, and `HttpMiddleware`.
 
-The class organizes the response into three properties:
+`HttpResponseBody` is an interface organized into three properties:
 
 ```ts
-new HttpResponseBody(data, errors, links)
+import type { HttpResponseBody } from '../../shared/application/http.js'
+
+const body: HttpResponseBody = {
+    data,
+    errors,
+    links
+}
 ```
 
 `data` contains the operation data and accepts `null` when the response has no data:
 
 ```ts
-const body = new HttpResponseBody({ id: 'user-1' })
+const body: HttpResponseBody = {
+    data: {
+        id: 'user-1',
+        name: 'Ana'
+    },
+    errors: null,
+    links: null
+}
 ```
 
 `errors` contains a list of messages:
 
 ```ts
-const body = new HttpResponseBody(
-    null,
-    ['The email is invalid.']
-)
+const body: HttpResponseBody = {
+    data: null,
+    errors: ['The email is invalid.'],
+    links: null
+}
 ```
 
 `links` contains HATEOAS links related to the resource and its available operations:
 
 ```ts
-const body = new HttpResponseBody(
-    { id: 'user-1' },
-    null,
-    {
+const body: HttpResponseBody = {
+    data: {
+        id: 'user-1',
+        name: 'Ana'
+    },
+    errors: null,
+    links: {
         self: new URL('https://api.example.com/users/user-1')
     }
-)
+}
 ```
 
 An entity's plain output can be used as `data`:
 
 ```ts
-const body = new HttpResponseBody(user.toJSON())
+const body: HttpResponseBody = {
+    data: user.toJSON(),
+    errors: null,
+    links: null
+}
 ```
 
+`HttpRequestHandler` and `HttpMiddleware` define the contracts for adapters that receive a request, delegate to a handler, and produce a response.
+
 ### Logs
 
 The `shared/application/loggers.ts` file declares the `Logger` contract. The application uses this abstraction to produce logs that an adapter sends to external services.
@@ -649,8 +706,6 @@ The contract includes the `debug`, `info`, `warning`, `error`, and `critical` le
 
 We will create a simple adapter that connects the contract to the console.
 
-**`users/adapters/console-logger-adapter.ts`**
-
 ```ts
 import { Logger } from '../../shared/application/loggers.js'
 
@@ -677,7 +732,7 @@ export class ConsoleLoggerAdapter extends Logger {
 }
 ```
 
-The service receives `Logger` as a dependency. The adapter decides where to send each level.
+In this example, the service receives `Logger` as a dependency. The adapter decides where to send each level.
 
 ### Events
 
@@ -701,14 +756,12 @@ EventHandler
 
 `Event` represents something that occurred in the application. It contains the event time and its plain details.
 
-**`users/application/user-created.ts`**
-
 ```ts
 import { Event } from '../../shared/application/events.js'
 
 export class UserCreated extends Event {
-    public constructor(userId: string) {
-        super(Date.now(), { userId })
+    public constructor(details: { userId: string }) {
+        super(Date.now(), details)
     }
 }
 ```
@@ -717,8 +770,6 @@ export class UserCreated extends Event {
 
 `EventHandler` represents a reaction to the event.
 
-**`users/application/log-user-created.ts`**
-
 ```ts
 import {
     Event,
@@ -747,16 +798,16 @@ unsubscribe(key, handler)
 dispatch(event)
 ```
 
-The service can receive `EventDispatcher` and publish `UserCreated` after completing the use case.
+In one possible implementation, the service can receive `EventDispatcher` and publish `UserCreated` after completing the use case.
 
 ## Data sources
 
-The `shared/application/data-sources.ts` file organizes access to a data source into four components: `DriverManager`, `DataManager`, `DatasetManager`, and `Repository`.
+The `shared/application/data/` directory organizes access to a data source into three modules: `drivers.ts`, `managers.ts`, and `repositories.ts`. Together, they define `DriverAdapter`, `DataManager`, `DatasetManager`, and `Repository`.
 
 The complete flow looks like this:
 
 ```text
-DriverManager
+DriverAdapter
     ↓ connects and enables
 DataManager or DatasetManager
     ↓ provides plain data to
@@ -769,37 +820,47 @@ Service
 
 We will begin with the connection and proceed to the use case.
 
-### Driver manager
+### Driver adapter
 
-`DriverManager` connects and disconnects the source through a driver. When the connection is available, `connect()` returns an enabled data manager.
+`DriverAdapter` connects and disconnects the source through a driver. When the connection is available, `connect()` returns an enabled data manager.
 
 ```ts
 connect(...args): Promise<DataManager>
 disconnect(): Promise<unknown>
 ```
 
-We will create a manager for an in-memory collection of people. The example avoids a database so the focus remains on the manager's responsibility.
-
-**`users/adapters/people-driver-manager.ts`**
+We will create an adapter for an in-memory collection of users. This example avoids a database so the focus stays on the adapter's responsibility, not on infrastructure details.
 
 ```ts
-import { DriverManager } from '../../shared/application/data-sources.js'
-import { PeopleDataManager } from './people-data-manager.js'
+import { DriverAdapter } from '../../shared/application/data/drivers.js'
+import { DataManager } from '../../shared/application/data/managers.js'
 
-export type PersonRecord = {
+type UserRecord = {
     id: string
     name: string
+    email: string
+    active: boolean | null
+}
+
+class UserDataManager extends DataManager<UserRecord> {
+    public constructor(private readonly records: UserRecord[]) {
+        super()
+    }
+
+    public async all(): Promise<UserRecord[]> {
+        return this.records
+    }
 }
 
-export class PeopleDriverManager
-    extends DriverManager<PeopleDataManager> {
+export class UserDriverAdapter
+    extends DriverAdapter<UserDataManager> {
 
-    public constructor(private readonly records: PersonRecord[]) {
+    public constructor(private readonly records: UserRecord[]) {
         super()
     }
 
-    public async connect(): Promise<PeopleDataManager> {
-        return new PeopleDataManager(this.records)
+    public async connect(): Promise<UserDataManager> {
+        return new UserDataManager(this.records)
     }
 
     public async disconnect(): Promise<void> {
@@ -811,54 +872,52 @@ The concrete implementation can encapsulate a database driver, an HTTP client, a
 
 ### Data manager
 
-`DataManager` operates on the source and works with plain objects and arrays. Its base form defines two operations:
+`DataManager` operates on the source and works with plain objects and arrays. Its base form exposes one abstract operation and one default operation:
 
 ```ts
 all(): Promise<Array<T>>
 none(): Array<T>
 ```
 
-`all()` retrieves the available records. `none()` creates an empty typed collection.
+`all()` retrieves the available records. `none()` already creates an empty typed collection.
 
 First, we will define the shape used by the source:
 
 ```ts
-type PersonRecord = {
+type UserRecord = {
     id: string
     name: string
+    email: string
+    active: boolean | null
 }
 ```
 
 Now we will implement the data manager.
 
-**`users/adapters/people-data-manager.ts`**
-
 ```ts
-import { DataManager } from '../../shared/application/data-sources.js'
+import { DataManager } from '../../shared/application/data/managers.js'
 
-export type PersonRecord = {
+export type UserRecord = {
     id: string
     name: string
+    email: string
+    active: boolean | null
 }
 
-export class PeopleDataManager
-    extends DataManager<PersonRecord> {
+export class UserDataManager
+    extends DataManager<UserRecord> {
 
-    public constructor(private readonly records: PersonRecord[]) {
+    public constructor(private readonly records: UserRecord[]) {
         super()
     }
 
-    public async all(): Promise<PersonRecord[]> {
+    public async all(): Promise<UserRecord[]> {
         return this.records
     }
-
-    public none(): PersonRecord[] {
-        return []
-    }
 }
 ```
 
-The data manager reflects the structure of the source. In this example, it only provides plain records.
+The data manager reflects the structure of the source. In this example, it only exposes plain records.
 
 #### Source operations
 
@@ -881,36 +940,32 @@ import {
     Creatable,
     DataManager,
     Filterable
-} from '../../shared/application/data-sources.js'
+} from '../../shared/application/data/managers.js'
 
-export class PeopleDataManager
-    extends DataManager<PersonRecord>
+export class UserDataManager
+    extends DataManager<UserRecord>
     implements
-        Filterable<Partial<PersonRecord>>,
-        Creatable<PersonRecord> {
+        Filterable<Partial<UserRecord>>,
+        Creatable<UserRecord> {
 
-    public constructor(private readonly records: PersonRecord[]) {
+    public constructor(private readonly records: UserRecord[]) {
         super()
     }
 
-    public async all(): Promise<PersonRecord[]> {
+    public async all(): Promise<UserRecord[]> {
         return this.records
     }
 
-    public none(): PersonRecord[] {
-        return []
-    }
-
     public async filter(
-        selector: Partial<PersonRecord>
-    ): Promise<PersonRecord[]> {
+        selector: Partial<UserRecord>
+    ): Promise<UserRecord[]> {
         return this.records.filter((record) =>
             (selector.id === undefined || record.id === selector.id) &&
-            (selector.name === undefined || record.name === selector.name)
+            (selector.email === undefined || record.email === selector.email)
         )
     }
 
-    public async create(data: PersonRecord): Promise<void> {
+    public async create(data: UserRecord): Promise<void> {
         this.records.push(data)
     }
 }
@@ -919,8 +974,8 @@ export class PeopleDataManager
 It can also declare operations specific to source queries:
 
 ```ts
-public async findByName(name: string): Promise<PersonRecord[]> {
-    return this.filter({ name })
+public async findByEmail(query: { email: string }): Promise<UserRecord[]> {
+    return this.filter({ email: query.email })
 }
 ```
 
@@ -934,7 +989,7 @@ The application layer decides when to execute these operations, combines their r
 union()
 intersection()
 difference()
-symmetric_difference()
+symmetricDifference()
 complement()
 ```
 
@@ -945,143 +1000,138 @@ This implementation is useful when an operation works with unions, intersections
 `Repository` acts as an intermediary between plain data and domain objects.
 
 ```text
-PersonRecord
+UserRecord
     ↓ transform
-Person
-
-Person
-    ↓ toRecord
-PersonRecord
+User
 ```
 
-In this example, the source and the domain have nearly the same shape so the focus remains on the repository's role: translating between plain data and domain objects.
+The generated base class focuses on reading plain data and transforming it into domain objects. Using the `UserDriverAdapter` from the previous example, a repository can stay very small.
 
-**`users/domain/person.ts`**
+Now we will implement the repository.
 
 ```ts
-import { Entity } from '../../shared/domain/entities.js'
+import { DriverAdapter } from '../../shared/application/data/drivers.js'
+import { DataManager } from '../../shared/application/data/managers.js'
+import { Repository } from '../../shared/application/data/repositories.js'
+import {
+    Email,
+    NullableBoolean
+} from '../../shared/domain/value-objects.js'
 
-export class Person extends Entity {
-    public constructor(
-        public readonly id: string,
-        public readonly name: string
-    ) {
-        super()
-    }
+type UserRecord = {
+    id: string
+    name: string
+    email: string
+    active: boolean | null
+}
 
-    public override equals(other: Entity): boolean {
-        return other instanceof Person && other.id === this.id
-    }
+class UserName {
+    public constructor(public readonly value: string) {}
 
-    public override toJSON(): Record<string, unknown> {
-        return {
-            id: this.id,
-            name: this.name
-        }
+    public static from(value: string): UserName {
+        return new UserName(value)
     }
 }
-```
-
-Now we will implement the repository.
 
-**`users/adapters/people-repository.ts`**
-
-```ts
-import { Repository } from '../../shared/application/data-sources.js'
-import type { PeopleReader } from '../application/list-people-service.js'
-import { Person } from '../domain/person.js'
-import type { PersonRecord } from './people-data-manager.js'
-import { PeopleDriverManager } from './people-driver-manager.js'
-
-export class PeopleRepository
-    extends Repository<PeopleDriverManager>
-    implements PeopleReader {
-
-    protected transform<T = Person>(data: Generic): T {
-        const record = data as PersonRecord
+class User {
+    public constructor(
+        public readonly id: string,
+        public readonly name: UserName,
+        public readonly email: Email,
+        public readonly active: NullableBoolean
+    ) {}
+}
 
-        return new Person(record.id, record.name) as T
-    }
+export class UserRepository
+    extends Repository<UserRecord, User> {
 
-    private toRecord(person: Person): PersonRecord {
-        return {
-            id: person.id,
-            name: person.name
-        }
+    public constructor(
+        driver: DriverAdapter<DataManager<UserRecord>>
+    ) {
+        super(driver)
     }
 
-    public async findAll(): Promise<Person[]> {
-        const dataManager = await this.manager.connect()
-        const records = await dataManager.all()
-
-        return records.map((record) =>
-            this.transform<Person>(record)
+    protected override transform(data: UserRecord): User {
+        return new User(
+            data.id,
+            UserName.from(data.name),
+            Email.from(data.email),
+            NullableBoolean.from(data.active)
         )
     }
-
-    public async save(person: Person): Promise<void> {
-        const dataManager = await this.manager.connect()
-
-        await dataManager.create(this.toRecord(person))
-    }
 }
 ```
 
-`transform()` converts the record into an entity. `toRecord()` performs the reverse conversion.
+Here, `transform()` converts each record into an entity. The constructor receives any driver compatible with `DataManager<UserRecord>`, and the inherited `all()` method already handles the connect, read, transform, and disconnect flow.
 
 ### Queries and errors in the application
 
 Application services coordinate queries and catch errors from data sources. The process expresses the collaboration capabilities it needs through application-specific contracts. Adapters materialize those contracts.
 
-**`users/application/list-people-service.ts`**
-
 ```ts
 import { Service } from '../../shared/application/services.js'
-import type { Person } from '../domain/person.js'
 
-export interface PeopleReader {
-    findAll(): Promise<Person[]>
+type User = {
+    id: string
 }
 
-export class ListPeopleService extends Service {
-    public constructor(private readonly people: PeopleReader) {
+export interface UsersReader {
+    all(): Promise<User[]>
+}
+
+export class ListUsersService extends Service {
+    public constructor(private readonly users: UsersReader) {
         super()
     }
 
-    public async execute(): Promise<Person[]> {
+    public async execute(): Promise<{ users: User[] }> {
         try {
-            return await this.people.findAll()
+            return {
+                users: await this.users.all()
+            }
         } catch {
-            throw new Error('Could not list people.')
+            throw new Error('Could not list users.')
         }
     }
 }
 ```
 
-`PeopleReader` expresses the collaboration required by the process. `PeopleRepository`, located in `adapters`, implements that collaboration and transforms source data into `Person` entities.
+`UsersReader` expresses the collaboration required by the process. `UserRepository`, located in `adapters`, already satisfies that collaboration through the inherited `all()` method.
 
 ## Context ports
 
 Ports describe communication between the context and other systems. Each port defines the shape of an interaction at the boundary: input data, output data, and the available operation.
 
-The context generates `index.ts` as the main port file and `example-ports.ts` as an example of an additional file. Adapters import the ports that define the communication they materialize.
+The context generates `example-ports.ts` as a root-level starting point. As the context grows, you can add `index.ts` as the main port file or split ports across multiple `.ts` files. Adapters import the ports that define the communication they materialize.
 
 ### Main port
 
-We will declare the communication for creating a user directly in `users/index.ts`.
+The generated `example-ports.ts` file is only a placeholder:
 
-**`users/index.ts`**
+```ts
+export function example(): void {
+    // ...
+}
+```
+
+You can replace it with your own root-level contract. A minimal option for creating a user is:
 
 ```ts
 export type CreateUserRequest = {
-    id: string
-    email: string
+    user: {
+        id: string
+        name: string
+        email: string
+    }
 }
 
 export type CreateUserResponse = {
-    id: string
-    email: string
-    active: boolean | null
+    user: {
+        id: string
+        name: string
+        email: string
+        active: boolean | null
+    }
 }
 
 export interface CreateUserPort {
@@ -1095,20 +1145,22 @@ export interface CreateUserPort {
 
 ### Adapt the port to the application process
 
-The adapter imports the port and the service. Its responsibility is to translate the external request into the application command and transform the result into the port response.
-
-**`users/adapters/create-user-adapter.ts`**
+In this example, the adapter imports the port and the service. Its job here is to translate the root-level contract into the application input object and return the service result.
 
 ```ts
 import type {
     CreateUserPort,
     CreateUserRequest,
     CreateUserResponse
-} from '../index.js'
-import {
-    CreateUserService,
-    type CreateUserCommand
-} from '../application/create-user-service.js'
+} from '../example-ports.js'
+
+type CreateUserService = {
+    execute(data: {
+        id: string
+        name: string
+        email: string
+    }): Promise<CreateUserResponse>
+}
 
 export class CreateUserAdapter implements CreateUserPort {
     public constructor(
@@ -1118,332 +1170,70 @@ export class CreateUserAdapter implements CreateUserPort {
     public async create(
         request: CreateUserRequest
     ): Promise<CreateUserResponse> {
-        const command: CreateUserCommand = {
-            id: request.id,
-            email: request.email
-        }
-
-        const result = await this.service.execute(command)
-
-        return {
-            id: result.id,
-            email: result.email,
-            active: result.active
-        }
+        return this.service.execute({
+            id: request.user.id,
+            name: request.user.name,
+            email: request.user.email
+        })
     }
 }
 ```
 
-The port expresses the communication. The adapter implements it. The service executes the process. The domain provides the capabilities used by that process.
+In this example, the port expresses the communication, the adapter implements it, the service executes the process, and the domain provides the capabilities used by that process.
 
 ### Additional ports
 
 A context can organize its communications across several files at the root. Each file declares the ports for a group of interactions.
 
-**`users/example-ports.ts`**
-
-```ts
-export type FindUserRequest = {
-    id: string
-}
-
-export type FindUserResponse = {
-    id: string
-    email: string
-} | null
-
-export interface FindUserPort {
-    find(
-        request: FindUserRequest
-    ): Promise<FindUserResponse>
-}
-```
-
-The corresponding adapter imports the contract from the file where it is declared:
-
 ```ts
-import type {
-    FindUserPort,
-    FindUserRequest,
-    FindUserResponse
-} from '../example-ports.js'
-```
-
-> **Tip:** group ports that form a coherent communication in the same file. Use additional files when the context grows and groups of interactions with their own responsibilities emerge.
-
-## Implement a context
-
-We will now walk through a complete implementation of `users`, following the layer order: capabilities, process, and communication.
-
-### 1. Model the domain capabilities
-
-We begin with concepts that have rules and behavior. We use `Email` for the email address, `string` for identity, and an entity for the user.
-
-**`users/domain/user.ts`**
-
-```ts
-import { Entity } from '../../shared/domain/entities.js'
-import {
-    Email,
-    NullableBoolean
-} from '../../shared/domain/value-objects.js'
-
-export class User extends Entity {
-    public constructor(
-        public readonly id: string,
-        public readonly email: Email,
-        public readonly active: NullableBoolean
-    ) {
-        super()
-    }
-
-    public override equals(other: Entity): boolean {
-        return other instanceof User && other.id === this.id
-    }
-
-    public override toJSON(): Record<string, unknown> {
-        return {
-            id: this.id,
-            email: this.email.value,
-            active: this.active.value
-        }
-    }
-}
-```
-
-`Email` provides the capability to validate and represent the email address. `User` provides user identity and representation.
-
-### 2. Implement process validation
-
-The validation prepares the input used by the use case.
-
-**`users/application/create-user-validation.ts`**
-
-```ts
-import type { Validatable } from '../../shared/application/validations.js'
-import { Email } from '../../shared/domain/value-objects.js'
-
-export class CreateUserValidation implements Validatable {
-    public constructor(private readonly email: string) {}
-
-    public isValid(): boolean {
-        return Email.isValid(this.email)
-    }
-
-    public validate(): string[] {
-        return this.isValid()
-            ? []
-            : ['The email is invalid.']
-    }
-}
-```
-
-### 3. Implement the application process
-
-The service receives its collaborators as dependencies and applies domain capabilities to complete the registration.
-
-**`users/application/create-user-service.ts`**
-
-```ts
-import { Service } from '../../shared/application/services.js'
-import {
-    Email,
-    NullableBoolean
-} from '../../shared/domain/value-objects.js'
-import { User } from '../domain/user.js'
-import { CreateUserValidation } from './create-user-validation.js'
-
-export interface UserWriter {
-    save(user: User): Promise<void>
-}
-
-export type CreateUserCommand = {
-    id: string
-    email: string
-}
-
-export type CreatedUser = {
-    id: string
-    email: string
+export type ListUsersRequest = {
     active: boolean | null
 }
 
-export class CreateUserService extends Service {
-    public constructor(private readonly users: UserWriter) {
-        super()
-    }
-
-    public async execute(
-        command: CreateUserCommand
-    ): Promise<CreatedUser> {
-        const validation = new CreateUserValidation(command.email)
-        const errors = validation.validate()
-
-        if (errors.length !== 0) {
-            throw new Error(errors.join(', '))
-        }
-
-        const user = new User(
-            command.id,
-            Email.from(command.email),
-            NullableBoolean.from(true)
-        )
-
-        await this.users.save(user)
-
-        return {
-            id: user.id,
-            email: user.email.value,
-            active: user.active.value
-        }
-    }
-}
-```
-
-`UserWriter` declares the operation the service requires from the adapter. The flow has four steps: validate, construct the entity, save, and respond.
-
-### 4. Declare the communication port
-
-The port defines how another system requests user creation.
-
-**`users/index.ts`**
-
-```ts
-export type CreateUserRequest = {
-    id: string
-    email: string
-}
-
-export type CreateUserResponse = {
-    id: string
-    email: string
-    active: boolean | null
+export type ListUsersResponse = {
+    users: Array<{
+        id: string
+        name: string
+        email: string
+        active: boolean | null
+    }>
 }
 
-export interface CreateUserPort {
-    create(
-        request: CreateUserRequest
-    ): Promise<CreateUserResponse>
+export interface ListUsersPort {
+    list(request: ListUsersRequest): Promise<ListUsersResponse>
 }
 ```
 
-### 5. Implement the adapter
-
-The adapter imports the port, receives the external request, and executes the application process.
-
-**`users/adapters/create-user-adapter.ts`**
+An adapter can import the contract from the file where it is declared:
 
 ```ts
 import type {
-    CreateUserPort,
-    CreateUserRequest,
-    CreateUserResponse
-} from '../index.js'
-import {
-    CreateUserService,
-    type CreateUserCommand
-} from '../application/create-user-service.js'
-
-export class CreateUserAdapter implements CreateUserPort {
-    public constructor(
-        private readonly service: CreateUserService
-    ) {}
-
-    public async create(
-        request: CreateUserRequest
-    ): Promise<CreateUserResponse> {
-        const command: CreateUserCommand = {
-            id: request.id,
-            email: request.email
-        }
-
-        const result = await this.service.execute(command)
-
-        return {
-            id: result.id,
-            email: result.email,
-            active: result.active
-        }
-    }
-}
-```
-
-The complete communication follows this path:
-
-```text
-External request
-      ↓
-CreateUserAdapter
-      ↓
-CreateUserService
-      ↓
-Validation + Email + User
-      ↓
-     UserWriter
-      ↓
-External response
-```
-
-### 6. Compose the implementation in `main.ts`
-
-`main.ts` brings together the library's main implementations. The composition creates the service and provides it to the adapter.
-
-**`core/main.ts`**
-
-```ts
-import { CreateUserService } from './users/application/create-user-service.js'
-import { CreateUserAdapter } from './users/adapters/create-user-adapter.js'
-import { InMemoryUserRepository } from './users/adapters/in-memory-user-repository.js'
-
-export class CoreApplication {
-    public readonly users: CreateUserAdapter
-
-    public constructor() {
-        const users = new InMemoryUserRepository()
-        const createUserService = new CreateUserService(users)
-
-        this.users = new CreateUserAdapter(createUserService)
-    }
-}
-```
-
-`CoreApplication` provides a minimal composition: a concrete repository, a service, and an adapter.
-
-### 7. Use the implementation
-
-The consumer uses the library's main entry point and accesses the adapter prepared in `main.ts`.
-
-```ts
-import { CoreApplication } from './core/main.js'
-
-const core = new CoreApplication()
-
-const result = await core.users.create({
-    id: 'user-1',
-    email: 'alejandro@example.com'
-})
+    ListUsersPort,
+    ListUsersResponse
+} from '../example-ports.js'
 ```
 
-The adapter receives the request, applies the port, executes the service, and returns the response.
+> **Tip:** group ports that form a coherent communication in the same file. Use additional files when the context grows and groups of interactions with their own responsibilities emerge.
 
 ## Generated file reference
 
 | File | Purpose |
 | --- | --- |
 | `core/index.d.ts` | Declares `Generic<T>` for plain objects. |
-| `core/main.ts` | Contains the library's main implementation. |
+| `core/main.ts` | Starts as a placeholder for the library's main implementation and exports. |
 | `shared/domain/value-objects.ts` | Declares `ValueObject<T>` and implements `Email` and `NullableBoolean`. |
 | `shared/domain/entities.ts` | Declares the `Entity` base class. |
 | `shared/domain/aggregates.ts` | Declares the `Aggregate` base class. |
 | `shared/domain/errors.ts` | Implements `ValueError`. |
 | `shared/application/validations.ts` | Declares `Validatable`. |
 | `shared/application/services.ts` | Declares `Service` as the base class for use cases. |
-| `shared/application/http.ts` | Implements `HttpResponseBody` for REST responses and HATEOAS links. |
+| `shared/application/http.ts` | Declares HTTP request, response, body, handler, and middleware contracts. |
 | `shared/application/loggers.ts` | Declares log levels and the `Logger` contract. |
 | `shared/application/events.ts` | Declares `Event`, `EventHandler`, and `EventDispatcher`. |
-| `shared/application/data-sources.ts` | Declares source operations, managers, and repositories. |
-| `users/index.ts` | Declares the context's main communication ports. |
-| `users/example-ports.ts` | Shows an additional communication port file. |
+| `shared/application/data/drivers.ts` | Declares the `DriverAdapter` contract used to connect to a data source. |
+| `shared/application/data/managers.ts` | Declares source operations together with `DataManager` and `DatasetManager`. |
+| `shared/application/data/repositories.ts` | Declares the `Repository` base class for transforming records into domain objects. |
+| `users/example-ports.ts` | Provides a root-level starter file with a placeholder export for your context ports. |
 | `users/domain/` | Contains the context's capabilities. |
 | `users/application/` | Contains processes that apply domain capabilities to fulfill purposes. |
 | `users/adapters/` | Contains integrations that import ports and connect the context with other systems. |