tshex-cli 1.0.29 → 1.0.30

package/docs/context-ports.md

@@ -21,7 +21,7 @@ surface that another actor can call or observe.
 
 The generated context starts with a single root file for ports.
 
-```ts title="users/example-ports.ts"
+```ts title="enrollment/example-ports.ts"
 export class ExamplePort {
     public doSomething(): void {
         // ...
@@ -39,32 +39,56 @@ expected to be a module that defines one or more context ports.
 #### First Port
 
 In the following example we replace the placeholder with a concrete port for
-creating a user.
+managing course enrollments.
 
-```ts title="users/example-ports.ts"
-export interface User {
-    id: string
-    email: string
-    active: boolean | null
-}
+```ts title="enrollment/example-ports.ts"
+import { InMemoryDatabaseDriver } from './application/database.ts'
+import { Course } from './domain/courses.ts'
+import { Student } from './domain/students.ts'
+import { InscriptionAggregate } from './domain/inscriptions.ts'
 
-export class UsersRegistry {
-    public async createUser(user: User): Promise<User> {
-        // ...
+const database: Record<string, Record<string, unknown>[]> = {}
+
+export class Example {
+    [property: string]: unknown
+
+    private readonly driver: InMemoryDatabaseDriver
+
+    constructor() {
+        this.driver = new InMemoryDatabaseDriver(database)
+    }
+
+    public createStudent(student: Student) {
+        const result = this.driver.connect('students').create(student.toJSON())
+        this.driver.disconnect()
+        return result
+    }
+
+    public createCourse(course: Course) {
+        const result = this.driver.connect('courses').create(course.toJSON())
+        this.driver.disconnect()
+        return result
     }
-}
-```
 
-`User` expresses the user data that crosses the boundary. `UsersRegistry` is a
-boundary object of the context and `createUser()` is one concrete capability
-that it exposes.
+    public listInscriptions() {
+        const result = this.driver.connect('inscriptions').all()
+        this.driver.disconnect()
+        return result
+    }
 
-This definition focuses on the interaction the context makes available. The
-port keeps its identity as one boundary capability while making its data and
-action explicit.
+    public createInscription(student: Student, course: Course) {
+        const inscription = InscriptionAggregate.enroll(student, course)
+        const result = this.driver.connect('inscriptions').create(inscription.toJSON())
+        this.driver.disconnect()
+        return result
+    }
+}
+```
 
-The port is the executable object that this context exposes. Types help
-describe it and make its boundary explicit.
+`Example` is a boundary object of the context. Each static method is one
+concrete capability it exposes. The port connects the boundary to a driver,
+uses domain concepts internally, and keeps infrastructure details out of the
+caller.
 
 This is the normal flow inside the context boundary:
 
@@ -83,10 +107,23 @@ capability and uses domain capabilities.
 
 As the context grows, you can keep several port modules at the context root.
 
-```ts title="users/registry.ts"
-export class UsersRegistry {
-    public async listUsers(): Promise<User[]> {
-        // ...
+```ts title="enrollment/courses.ts"
+import { CoursesService } from './application/services.ts'
+import { Course } from './domain/courses.ts'
+
+export class CoursesPort {
+    constructor(private readonly service: CoursesService) {}
+
+    public all(): Record<string, unknown>[] {
+        return this.service.all()
+    }
+
+    public create(name: string, description: string, hours: number): boolean {
+        return this.service.create(new Course(name, description, hours))
+    }
+
+    public delete(course: Course): boolean {
+        return this.service.delete(course)
     }
 }
 ```
@@ -110,9 +147,10 @@ in the generated folders.
 
 ```mermaid
 flowchart TD
-    users["users/"] --> registry["registry.ts"]
-    users --> application["application/"]
-    users --> domain["domain/"]
+    enrollment["enrollment/"] --> examplePort["example-ports.ts"]
+    enrollment --> courses["courses.ts"]
+    enrollment --> application["application/"]
+    enrollment --> domain["domain/"]
 ```
 
 This layout keeps the context boundary visible from the top level. It also

package/docs/generated-file-reference.md

@@ -85,8 +85,9 @@ The generated template also includes a small set of data-access abstractions.
 
 | File | Responsibility |
 | --- | --- |
+| `shared/application/data/capabilities.ts` | Declares the operation capability interfaces: `Listable`, `Filterable`, `Sortable`, `Creatable`, `Updatable`, `Deletable`, `Aggregatable`, and `Relatable`. |
 | `shared/application/data/drivers.ts` | Declares `DriverAdapter`, the connection contract with a data source. |
-| `shared/application/data/managers.ts` | Declares `DataManager`, `DatasetManager`, and plain-record operations. |
+| `shared/application/data/managers.ts` | Declares `DataManager` and `DatasetManager`. |
 | `shared/application/data/repositories.ts` | Declares `Repository`, which transforms raw records into domain representations. |
 
 These contracts belong to the application layer because they define how the

package/docs/library-structure.md

@@ -18,7 +18,7 @@ flowchart TD
     root["Library root"] --> types["types/"]
     root --> main["main.ts"]
     root --> shared["shared/"]
-    root --> users["users/"]
+    root --> enrollment["enrollment/"]
 ```
 
 `types/` groups the root-level type declarations. `main.ts` starts as a
@@ -69,7 +69,7 @@ capability.
 
 ```mermaid
 flowchart TD
-    contexts["Contexts"] --> users["users/"]
+    contexts["Contexts"] --> enrollment["enrollment/"]
     contexts --> billing["billing/"]
     contexts --> inventory["inventory/"]
     contexts --> sales["sales/"]
@@ -85,10 +85,10 @@ Every generated context starts with the same internal structure.
 
 ```mermaid
 flowchart TD
-    users["users/"] --> ports["example-ports.ts"]
-    users --> adapters["adapters/"]
-    users --> application["application/"]
-    users --> domain["domain/"]
+    enrollment["enrollment/"] --> ports["example-ports.ts"]
+    enrollment --> adapters["adapters/"]
+    enrollment --> application["application/"]
+    enrollment --> domain["domain/"]
 ```
 
 `example-ports.ts` is an example module in the root communication surface of
@@ -189,6 +189,22 @@ application services use domain capabilities, while adapters can depend on
 ports and third-party libraries. The port branch stops at the boundary because
 what exists beyond that port depends on the system that implements it.
 
+```ts title="main.ts"
+import { Example } from './enrollment/example-ports.ts'
+import { Student } from './enrollment/domain/students.ts'
+import { Course } from './enrollment/domain/courses.ts'
+
+const example = new Example()
+const student = new Student('Ada Lovelace', 'ada@example.com')
+const course = new Course('Mathematics', 'Fundamentals of algebra and calculus', 40)
+
+example.createStudent(student)
+example.createCourse(course)
+example.createInscription(student, course)
+
+console.log(example.listInscriptions())
+```
+
 #### Next Step
 
 Use this structure as the default layout for new code. When you need to inspect

package/docs/shared/application/data.md

@@ -1,188 +1,259 @@
 ### Data
 
 The data contracts define how the application layer interacts with plain source
-records.
-They separate connection management, raw record access, and domain
+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:
+The generated structure splits this concern into four files:
 
-1. `drivers.ts` for connection adapters;
-2. `managers.ts` for plain-record operations;
-3. `repositories.ts` for record-to-domain transformation.
+1. `capabilities.ts` for operation capability interfaces;
+2. `drivers.ts` for connection adapters;
+3. `managers.ts` for plain-record operations;
+4. `repositories.ts` for record-to-domain transformation.
 
-#### Driver Adapter
+#### Capabilities
 
-`DriverAdapter` is responsible for connecting to a data source and returning an
-enabled `DataManager`.
+`capabilities.ts` declares the operation interfaces that a manager implements
+to advertise what it supports.
 
-```ts title="shared/application/data/drivers.ts"
-import { DataManager } from './managers.js'
+```ts title="shared/application/data/capabilities.ts"
+export interface Listable<DataShape extends Generic = Generic> {
+    all(): DataShape[]
+}
 
-export abstract class DriverAdapter<M extends DataManager = DataManager> {
-    public abstract connect(...args: unknown[]): Promise<M>
+export interface Creatable<DataShape extends Generic = Generic, Feedback = unknown> {
+    create(data: DataShape): Feedback
+}
 
-    public abstract disconnect(): Promise<unknown>
+export interface Deletable<Selector = unknown, Feedback = unknown> {
+    delete(selector: Selector): Feedback
 }
+
+// Also available: Filterable, Sortable, Updatable, Aggregatable, Relatable
 ```
 
-The `connect()` method returns a manager that can read or manipulate raw data.
-The `disconnect()` method closes the interaction when the work is finished.
+Implement only the interfaces that the manager actually supports. Adding
+`Creatable` to a class makes the creation capability explicit and discoverable
+without adding it to the base class.
+
+```ts title="enrollment/application/managers.ts"
+import { DataManager } from '../shared/application/data/managers.ts'
+import type {
+    Listable,
+    Creatable,
+    Deletable
+} from '../shared/application/data/capabilities.ts'
+import type { Course } from '../domain/courses.ts'
+import type { Student } from '../domain/students.ts'
+import type { Inscription } from '../domain/inscriptions.ts'
+
+type Generic = Record<string, unknown>
+
+export type CourseData = ReturnType<Course['toJSON']>
+export type StudentData = ReturnType<Student['toJSON']>
+export type InscriptionData = ReturnType<Inscription['toJSON']>
+
+export class InMemoryDatabaseManager
+    extends DataManager
+    implements Listable, Creatable, Deletable
+{
+    [property: string]: unknown
+
+    constructor(private records: Generic[]) {
+        super()
+    }
+
+    public all(): Generic[] {
+        return this.records
+    }
+
+    public create(data: Generic): boolean {
+        this.records.push(data)
+        return true
+    }
+
+    public delete(selector: Partial<Generic>): boolean {
+        const before = this.records.length
+        this.records = this.records.filter((record) =>
+            Object.entries(selector).every(([key, value]) => record[key] !== value)
+        )
+        return this.records.length < before
+    }
+}
+```
 
 #### Data Manager
 
-`DataManager` is responsible for exposing plain source data.
+`DataManager` is the base contract for any data source. `DatasetManager`
+extends it with set operations for contexts that need to combine collections.
 
 ```ts title="shared/application/data/managers.ts"
 export abstract class DataManager<T = Record<string, unknown>> {
-    public none(): Array<T> {
-        return []
-    }
+    [property: string]: unknown
+}
+
+export abstract class DatasetManager<T = Record<string, unknown>> extends DataManager<T> {
+    [property: string]: unknown
 
-    public abstract all(): Promise<Array<T>>
+    public abstract union(other: Array<T>): Array<T>
+    public abstract intersection(other: Array<T>): Array<T>
+    public abstract difference(other: Array<T>): Array<T>
+    public abstract symmetricDifference(other: Array<T>): Array<T>
+    public abstract complement(other: Array<T>): 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.
+Extend `DataManager` to implement a concrete data source. The manager exposes
+raw data without domain transformation. The `InMemoryDatabaseManager` above
+extends `DataManager` and implements `Listable`, `Creatable`, and `Deletable`.
 
-#### Implementation
+#### Driver Adapter
+
+`DriverAdapter` is responsible for connecting to a data source and returning an
+enabled `DataManager`.
 
-In the following example we implement an in-memory manager and its driver.
+```ts title="shared/application/data/drivers.ts"
+export abstract class DriverAdapter<M extends DataManager = DataManager> {
+    [property: string]: unknown
 
-```ts title="users/adapters/memory-users-driver.ts"
-import { DriverAdapter } from '../../shared/application/data/drivers.js'
-import { DataManager } from '../../shared/application/data/managers.js'
+    public abstract connect(...args: unknown[]): M
 
-type UserRecord = {
-    id: string
-    email: string
-    active: boolean | null
+    public abstract disconnect(): unknown
 }
+```
 
-class MemoryUsersManager extends DataManager<UserRecord> {
-    public constructor(private readonly rows: Array<UserRecord>) {
-        super()
-    }
+Extend `DriverAdapter` to wrap a concrete data source. The driver connects to
+the source, returns an enabled manager, and disconnects when the work is done.
 
-    public async all(): Promise<Array<UserRecord>> {
-        return this.rows
-    }
-}
+```ts title="enrollment/application/database.ts"
+import { DriverAdapter } from '../shared/application/data/drivers.ts'
+import { InMemoryDatabaseManager } from './managers.ts'
+
+type Generic = Record<string, unknown>
 
-export class MemoryUsersDriver extends DriverAdapter<MemoryUsersManager> {
-    public constructor(private readonly rows: Array<UserRecord>) {
+export type Database = Record<string, Generic[]>
+
+export class InMemoryDatabaseDriver extends DriverAdapter<InMemoryDatabaseManager> {
+    [property: string]: unknown
+
+    private manager: InMemoryDatabaseManager | null = null
+
+    constructor(private readonly database: Database) {
         super()
     }
 
-    public async connect(): Promise<MemoryUsersManager> {
-        return new MemoryUsersManager(this.rows)
+    public connect(collectionKey: string): InMemoryDatabaseManager {
+        if (this.database[collectionKey] === undefined) {
+            this.database[collectionKey] = []
+        }
+
+        this.manager = new InMemoryDatabaseManager(this.database[collectionKey])
+        return this.manager
     }
 
-    public async disconnect(): Promise<void> {
-        return undefined
+    public disconnect(): void {
+        this.manager = null
     }
 }
 ```
 
-`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.
+`InMemoryDatabaseDriver` owns the connection contract. `InMemoryDatabaseManager`
+owns the raw records. The application layer can use both without knowing whether
+the source is memory, SQL, or an HTTP-backed adapter.
 
-Put all your complex data operations in `DataManager`. `Repository` should only handle the transformation of raw records into domain representations. For example, if you need to relate users to their posts, implement that in a manager:
+#### Repository
 
-```ts
-class ComplexUsersManager extends DataManager<EnrichedUserRecord> {
-    ...
+`Repository` is responsible for transforming raw records into domain-oriented
+representations. It holds a reference to the manager and requires `transform()`
+to map a raw record into a domain entity.
 
-    public async findAllAndRelate(): Promise<Array<EnrichedUserRecord>> {
-        ...
-    }
+```ts title="shared/application/data/repositories.ts"
+export abstract class Repository<
+    RawDataShape = Generic,
+    EntityShape = Generic,
+    M extends DataManager<RawDataShape> = DataManager<RawDataShape>
+> {
+    [property: string]: unknown
+
+    public constructor(public readonly manager: M) {}
+
+    protected abstract transform(data: RawDataShape, ...args: unknown[]): EntityShape
 }
 ```
 
-#### Repository
+Data retrieval operations are not defined in the base class — add them
+explicitly in the concrete class using the capability interfaces from
+`capabilities.ts`.
 
-`Repository` is responsible for transforming raw records into domain-oriented
-representations.
+```ts title="enrollment/application/repositories.ts"
+import { Repository } from '../shared/application/data/repositories.ts'
+import { InMemoryDatabaseManager } from './managers.ts'
+import type { CourseData, StudentData, InscriptionData } from './managers.ts'
+import { Course } from '../domain/courses.ts'
+import { Student } from '../domain/students.ts'
+import { Inscription } from '../domain/inscriptions.ts'
 
-```ts title="shared/application/data/repositories.ts"
-import { type DataManager } from './managers.js'
-import { type DriverAdapter } from './drivers.js'
+export class CoursesRepository extends Repository<CourseData, Course, InMemoryDatabaseManager> {
+    [property: string]: unknown
 
-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>>) {}
+    constructor(manager: InMemoryDatabaseManager) {
+        super(manager)
+    }
 
-    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 transform(data: CourseData): Course {
+        return new Course(data.name, data.description, data.duration_hours)
     }
 
-    protected transformList(data: Array<DataShape>): Array<EntityShape> {
-        return data.map(this.transform)
+    public create(course: Course): boolean {
+        return this.manager.create(course.toJSON())
     }
 
-    protected abstract transform(data: DataShape): EntityShape
+    public delete(course: Course): boolean {
+        return this.manager.delete(course.toJSON())
+    }
 }
-```
 
-The base repository already defines the `all()` flow. A concrete repository only
-needs to implement `transform()`.
+export class StudentsRepository extends Repository<StudentData, Student, InMemoryDatabaseManager> {
+    [property: string]: unknown
 
-#### Repository Implementation
+    constructor(manager: InMemoryDatabaseManager) {
+        super(manager)
+    }
 
-Now that the driver exists, a repository can translate raw records into a shape
-that the rest of the context can use.
+    protected transform(data: StudentData): Student {
+        return new Student(data.name, data.email)
+    }
 
-```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'
+    public create(student: Student): boolean {
+        return this.manager.create(student.toJSON())
+    }
 
-type UserRecord = {
-    id: string
-    email: string
-    active: boolean | null
+    public delete(student: Student): boolean {
+        return this.manager.delete(student.toJSON())
+    }
 }
 
-type UserView = {
-    id: string
-    email: string
-    active: boolean | null
-}
+export class InscriptionsRepository extends Repository<InscriptionData, Inscription, InMemoryDatabaseManager> {
+    [property: string]: unknown
 
-export class UsersRepository extends Repository<UserRecord, UserView> {
-    public constructor(driver: DriverAdapter<DataManager<UserRecord>>) {
-        super(driver)
+    constructor(manager: InMemoryDatabaseManager) {
+        super(manager)
     }
 
-    protected transform(data: UserRecord): UserView {
-        return {
-            id: data.id,
-            email: data.email,
-            active: data.active,
-        }
+    protected transform(data: InscriptionData, student: Student, course: Course): Inscription {
+        return new Inscription(student, course, data.enrolled_at)
     }
-}
-```
 
-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.
+    public create(inscription: Inscription): boolean {
+        return this.manager.create(inscription.toJSON())
+    }
 
-> **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.
+    public delete(inscription: Inscription): boolean {
+        return this.manager.delete(inscription.toJSON())
+    }
+}
+```
 
 #### Example Flow
 
@@ -191,8 +262,7 @@ The normal flow of the data abstractions is the following:
 ```mermaid
 flowchart LR
     service[Service] --> repository[Repository]
-    repository --> driver[Driver]
-    driver --> manager["Data manager"]
+    repository --> manager["Data manager"]
     manager --> raw["Raw records"]
     repository --> transformed["Transformed records"]
     transformed --> service

package/docs/shared/application/services.md

@@ -1,9 +1,8 @@
 ### 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.
+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.
@@ -13,111 +12,115 @@ processes.
 `Service` is an abstract class with no concrete behavior.
 
 ```ts title="shared/application/services.ts"
-export abstract class Service {}
+export abstract class Service {
+    [property: string]: unknown
+}
 ```
 
 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.
+without imposing a method name, result shape, or framework-specific lifecycle.
+
+#### Usage
+
+In the following example we build services for a course enrollment context.
+Each service receives its dependencies through the constructor and exposes
+operations that the context ports can call.
+
+```ts title="enrollment/application/services.ts"
+import { Service } from '../shared/application/services.ts'
+import { InMemoryDatabaseManager } from './managers.ts'
+import { CoursesRepository, StudentsRepository, InscriptionsRepository } from './repositories.ts'
+import type { Course } from '../domain/courses.ts'
+import type { Student } from '../domain/students.ts'
+import type { Inscription } from '../domain/inscriptions.ts'
+
+export class CoursesService extends Service {
+    [property: string]: unknown
+
+    constructor(
+        private readonly manager: InMemoryDatabaseManager,
+        private readonly repository: CoursesRepository
+    ) {
+        super()
+    }
+
+    public all() {
+        return this.manager.all()
+    }
+
+    public create(course: Course) {
+        return this.repository.create(course)
+    }
+
+    public delete(course: Course) {
+        return this.repository.delete(course)
+    }
+}
 
-#### First Service
+export class StudentsService extends Service {
+    [property: string]: unknown
 
-In the following example we build a small registration process.
+    constructor(
+        private readonly manager: InMemoryDatabaseManager,
+        private readonly repository: StudentsRepository
+    ) {
+        super()
+    }
 
-```ts title="users/application/register-user.ts"
-import { Service } from '../../shared/application/services.js'
-import { Email, NullableBoolean } from '../../shared/domain/value-objects.js'
+    public all() {
+        return this.manager.all()
+    }
 
-type UserRecord = {
-	id: string
-	email: string
-	active: boolean | null
-}
+    public create(student: Student) {
+        return this.repository.create(student)
+    }
 
-type SaveUser = {
-	save(user: UserRecord): Promise<UserRecord>
+    public delete(student: Student) {
+        return this.repository.delete(student)
+    }
 }
 
-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,
-		})
-	}
-}
-```
+export class InscriptionsService extends Service {
+    [property: string]: unknown
+
+    constructor(
+        private readonly manager: InMemoryDatabaseManager,
+        private readonly repository: InscriptionsRepository
+    ) {
+        super()
+    }
+
+    public all() {
+        return this.manager.all()
+    }
+
+    public create(inscription: Inscription) {
+        return this.repository.create(inscription)
+    }
 
-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
-		}
-	}
+    public delete(inscription: Inscription) {
+        return this.repository.delete(inscription)
+    }
 }
 ```
 
-`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.
+Each service holds a reference to its manager and repository. The manager
+provides raw list access; the repository delegates creation and deletion
+through the domain entities.
 
 > **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.
+> `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
 
 ```mermaid
 flowchart LR
-    input[Input] --> service[Service]
-    service --> domain["Domain capabilities"]
-    domain --> collaborators[Collaborators]
-    collaborators --> result[Result]
+    port[Port] --> service[Service]
+    service --> repository[Repository]
+    service --> manager["Data manager"]
+    repository --> domain["Domain entities"]
 ```
 
 This flow keeps orchestration in the application layer and domain meaning in

package/docs/shared/domain/aggregates.md

@@ -11,148 +11,39 @@ The generated template provides `Aggregate` as a semantic base class.
 `Aggregate` is an abstract class with no concrete methods.
 
 ```ts title="shared/domain/aggregates.ts"
-export abstract class Aggregate {}
+export abstract class Aggregate {
+    [property: string]: unknown
+}
 ```
 
 The class is intentionally empty. Its role is to provide the semantic base for
-an aggregate whose concrete implementation gathers the involved entities as a
-key-value structure through its own properties, such as `buyer`, `seller`,
-`order`, or `invoice`. Persistence rules, event publication, and identity
-behavior live in the concrete domain model of the project.
-
-#### First Aggregate
-
-In the following example we model a sale as one domain unit composed of a
-buyer, a seller, an order, and an invoice generated by the aggregate itself.
-
-```ts title="sales/domain/sale.ts"
-import { Aggregate } from '../../shared/domain/aggregates.js'
-import { Entity } from '../../shared/domain/entities.js'
-
-class Person extends Entity {
-	public readonly id: string
-	public readonly name: string
-
-	public constructor(id: string, name: string) {
-		super()
-		this.id = id
-		this.name = name
-	}
+an aggregate whose concrete implementation gathers the involved entities and
+exposes operations that span more than one of them.
 
-	public equals(other: Entity): boolean {
-		return other instanceof Person && this.id === other.id
-	}
-}
-
-class Product extends Entity {
-	public readonly id: string
-	public readonly name: string
-	public readonly price: number
-
-	public constructor(id: string, name: string, price: number) {
-		super()
-		this.id = id
-		this.name = name
-		this.price = price
-	}
-
-	public equals(other: Entity): boolean {
-		return other instanceof Product && this.id === other.id
-	}
-}
+#### Usage
 
-class Order extends Entity {
-	public readonly id: string
-	public readonly products: Product[]
+In the following example we model an enrollment aggregate that groups a
+student and a course to produce an inscription with the current date.
 
-	public constructor(id: string, products: Product[]) {
-		super()
-		this.id = id
-		this.products = products
-	}
+```ts title="enrollment/domain/inscriptions.ts"
+import { Aggregate } from '../shared/domain/aggregates.ts'
+import { Course } from './courses.ts'
+import { Student } from './students.ts'
+import { Inscription } from './inscriptions.ts'
 
-	public equals(other: Entity): boolean {
-		return other instanceof Order && this.id === other.id
-	}
-}
-
-class Invoice extends Entity {
-	public readonly id: string
-	public readonly order: Order
-	public readonly buyer: Person
-	public readonly seller: Person
-	public readonly total: number
-
-	public constructor(
-		id: string,
-		order: Order,
-		buyer: Person,
-		seller: Person,
-	) {
-		super()
-		this.id = id
-		this.order = order
-		this.buyer = buyer
-		this.seller = seller
-		this.total = this.order.products.reduce(
-			(sum, product) => sum + product.price,
-			0,
-		)
-	}
-
-	public equals(other: Entity): boolean {
-		return other instanceof Invoice && this.id === other.id
-	}
-}
+export class InscriptionAggregate extends Aggregate {
+    [property: string]: unknown
 
-export class Sale extends Aggregate {
-	public readonly buyer: Person
-	public readonly seller: Person
-	public readonly order: Order
-	protected invoice: Invoice | null
-
-	public constructor(
-		buyer: Person,
-		seller: Person,
-		order: Order,
-	) {
-		super()
-		this.buyer = buyer
-		this.seller = seller
-		this.order = order
-		this.invoice = null
-	}
-
-	public generateInvoice(): { invoice: Invoice } {
-		const id = Math.random().toString()
-		const invoice = new Invoice(
-			id,
-			this.order,
-			this.buyer,
-			this.seller,
-		)
-
-		this.invoice = invoice
-
-		return { invoice }
-	}
-
-	public getInvoice(): Invoice | null {
-		return this.invoice
-	}
+    public static enroll(student: Student, course: Course): Inscription {
+        const currentDate = new Date()
+        return new Inscription(student, course, currentDate)
+    }
 }
 ```
 
-`Sale` is an aggregate because the rule for generating the invoice depends on
-the collaboration between buyer, seller, and order. In this example, both
-buyer and seller are modeled with the same `Person` entity, while `Order`
-stores the list of purchased products and `Invoice` stores the computed
-`total`. `Invoice` is created inside the aggregate, and its constructor
-calculates the total from the order products when the invoice is generated. The
-`invoice` field stays inside the aggregate lifecycle and `getInvoice()` offers
-controlled access to the generated invoice. When a domain object already
-exists, the example uses that object directly and keeps the collaboration
-between domain parts explicit.
+`InscriptionAggregate` centralizes the rule for creating an inscription. The
+enrollment date is set automatically, so callers do not pass it directly and
+the rule stays in one place.
 
 #### Responsibility Boundary
 

package/docs/shared/domain/entities.md

@@ -1,9 +1,8 @@
 ### Entities
 
 An entity is responsible for representing a domain concept with its own
-identity.
-Two entity instances refer to the same conceptual element when they share that
-identity, even if other attributes change over time.
+identity. Two entity instances refer to the same conceptual element when they
+share that identity, even if other attributes change over time.
 
 The generated template provides `Entity` as a base class for this pattern.
 
@@ -13,73 +12,119 @@ The generated template provides `Entity` as a base class for this pattern.
 
 ```ts title="shared/domain/entities.ts"
 export abstract class Entity {
-	public abstract equals(other: Entity): boolean
+    [property: string]: unknown
 
-	public toJSON(): Record<string, unknown> {
-		return this
-	}
+    public abstract equals(other: Entity): boolean
 
-	public toString(): string {
-		return String(this.constructor.name)
-	}
+    public toJSON(): Record<string, unknown> {
+        return this
+    }
+
+    public toString(): string {
+        return this.constructor.name
+    }
 }
 ```
 
-Every concrete entity must implement `equals()`. The generated base class also
-provides `toJSON()` and `toString()`.
-
-#### First Entity
-
-In the following example we model a user entity.
+Every concrete entity must implement `equals()`. Override `toJSON()` to control
+the plain representation returned when the entity is serialized.
 
-```ts title="users/domain/user.ts"
-import { Entity } from '../../shared/domain/entities.js'
-import { Email } from '../../shared/domain/value-objects.js'
+#### Usage
 
-export class User extends Entity {
-	public constructor(
-		public readonly id: string,
-		public readonly email: Email,
-	) {
-		super()
-	}
+In the following example we model the entities of a course enrollment context.
 
-	public equals(other: Entity): boolean {
-		return other instanceof User && this.id === other.id
-	}
-}
-```
+```ts title="enrollment/domain/students.ts"
+import { Entity } from '../shared/domain/entities.ts'
 
-The identity rule lives in `equals()`. The entity compares the `id`, not the
-email address, because the email can change while the entity still represents
-the same user.
+export class Student extends Entity {
+    [property: string]: unknown
 
-#### Included Behavior
+    constructor(
+        public name: string,
+        public email: string
+    ) {
+        super()
+    }
 
-Now that the entity exists, the inherited helpers become useful.
+    public equals(other: Student): boolean {
+        return this.email === other.email
+    }
 
-```ts
-const user = new User('usr_1', Email.from('ada@example.com'))
+    public override toJSON() {
+        return {
+            name: this.name,
+            email: this.email
+        }
+    }
+}
+```
 
-user.toString()
-user.toJSON()
+```ts title="enrollment/domain/courses.ts"
+import { Entity } from '../shared/domain/entities.ts'
+
+export class Course extends Entity {
+    [property: string]: unknown
+
+    constructor(
+        public name: string,
+        public description: string,
+        public duration_hours: number
+    ) {
+        super()
+    }
+
+    public equals(other: Course): boolean {
+        return this.name === other.name
+    }
+
+    public override toJSON() {
+        return {
+            name: this.name,
+            description: this.description,
+            duration_hours: this.duration_hours
+        }
+    }
+}
 ```
 
-`toString()` returns the constructor name. `toJSON()` returns the instance as a
-plain record, which is convenient for simple serialization or inspection.
+```ts title="enrollment/domain/inscriptions.ts"
+import { Entity } from '../shared/domain/entities.ts'
+import { Course } from './courses.ts'
+import { Student } from './students.ts'
+
+export class Inscription extends Entity {
+    [property: string]: unknown
+
+    constructor(
+        public readonly student: Student,
+        public readonly course: Course,
+        public readonly enrolled_at: Date
+    ) {
+        super()
+    }
+
+    public equals(other: Inscription): boolean {
+        return this.student.equals(other.student) && this.course.equals(other.course)
+    }
+
+    public override toJSON() {
+        return {
+            student: this.student.toJSON(),
+            course: this.course.toJSON(),
+            enrolled_at: this.enrolled_at
+        }
+    }
+}
+```
 
 #### Equality Rules
 
 The most important design decision in an entity is the identity comparison.
 
-Correct identity candidates usually include:
-
-1. a stable identifier;
-2. a natural domain key that does not drift over time;
-3. a combination of fields that the domain treats as unique.
-
-Changing fields that are not part of the identity should not make `equals()`
-return `false` for the same conceptual entity.
+`Student` uses `email` as the identity because two students with the same email
+represent the same person. `Course` uses `name`. `Inscription` combines the
+student and course identities — two inscriptions are the same when both the
+student and the course match.
 
 > **Hint**
 > Keep `equals()` explicit and small. If the comparison starts depending on many
@@ -88,4 +133,4 @@ return `false` for the same conceptual entity.
 #### Next Step
 
 When the identity of a concept is determined entirely by its value, use a value
-object instead. The generated abstraction is documented in `value-objects.md`.
+object instead. The generated abstraction is documented in `value-objects.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tshex-cli",
-  "version": "1.0.29",
+  "version": "1.0.30",
   "author": "https://github.com/virtualitems/",
   "license": "MIT",
   "description": "Typescript Hexagonal Architecture CLI",

package/templates/lib/shared/application/data/capabilities.ts

@@ -1,49 +1,53 @@
 type Generic = Record<string, unknown>
 
-export interface Listable {
-    all(): Generic | Promise<Generic[]>
+export interface Listable<DataShape extends Generic = Generic> {
+    all(): DataShape[]
 }
 
 /**
  * @description Declares a filtering operation over plain source records.
  */
-export interface Filterable {
-    filter(selector: unknown): Generic | Promise<Generic[]>
+export interface Filterable<DataShape extends Generic = Generic, Selector = unknown> {
+    filter(selector: Selector): DataShape[]
 }
 
 /**
  * @description Declares a sorting operation over plain source records.
  */
-export interface Sortable {
-    sort(selector: unknown): Generic | Promise<Generic[]>
+export interface Sortable<DataShape extends Generic = Generic, Selector = unknown> {
+    sort(selector: Selector): DataShape[]
 }
 
 /**
  * @description Declares a creation operation for plain source records.
  */
-export interface Creatable {
-    create(data: unknown): unknown
+export interface Creatable<DataShape extends Generic = Generic, Feedback = unknown> {
+    create(data: DataShape): Feedback
 }
 
 /**
  * @description Declares an update operation that selects source records and applies new plain data.
  */
-export interface Updatable {
-    update(selector: unknown, data: unknown): unknown
+export interface Updatable<
+    DataShape extends Generic = Generic,
+    Selector = unknown,
+    Feedback = unknown
+> {
+    update(selector: Selector, data: Partial<DataShape>): Feedback
 }
 
 /**
  * @description Declares a deletion operation over source records selected by plain criteria.
  */
-export interface Deletable {
-    delete(selector: unknown): unknown
+export interface Deletable<Selector = unknown, Feedback = unknown> {
+    delete(selector: Selector): Feedback
 }
 
 /**
  * @description Declares an aggregation operation over source records.
  */
-export interface Aggregatable {
-    aggregate(selector: unknown): unknown
+export interface Aggregatable<Selector = unknown, Feedback = unknown> {
+    aggregate(selector: Selector): Feedback
 }
 
 /**

package/templates/lib/shared/application/data/drivers.ts

@@ -9,7 +9,7 @@ import { DataManager } from './managers.js'
 export abstract class DriverAdapter<M extends DataManager = DataManager> {
     [property: string]: unknown
 
-    public abstract connect(...args: unknown[]): Promise<M>
+    public abstract connect(...args: unknown[]): M
 
-    public abstract disconnect(): Promise<unknown>
+    public abstract disconnect(): unknown
 } //:: class

package/templates/lib/shared/application/data/managers.ts

@@ -12,13 +12,13 @@ export abstract class DataManager<T = Record<string, unknown>> {
 export abstract class DatasetManager<T = Record<string, unknown>> extends DataManager<T> {
     [property: string]: unknown
 
-    public abstract union(other: Array<T>): Promise<Array<T>>
+    public abstract union(other: Array<T>): Array<T>
 
-    public abstract intersection(other: Array<T>): Promise<Array<T>>
+    public abstract intersection(other: Array<T>): Array<T>
 
-    public abstract difference(other: Array<T>): Promise<Array<T>>
+    public abstract difference(other: Array<T>): Array<T>
 
-    public abstract symmetricDifference(other: Array<T>): Promise<Array<T>>
+    public abstract symmetricDifference(other: Array<T>): Array<T>
 
-    public abstract complement(other: Array<T>): Promise<Array<T>>
+    public abstract complement(other: Array<T>): Array<T>
 } //:: class

package/templates/lib/shared/application/data/repositories.ts

@@ -1,5 +1,4 @@
 import { type DataManager } from './managers.js'
-import { type DriverAdapter } from './drivers.js'
 
 type Generic = Record<string, unknown>
 
@@ -7,12 +6,12 @@ type Generic = Record<string, unknown>
  * @description Acts as an intermediary between plain source data and domain objects.
  * It transforms records into domain representations and can translate them back when needed.
  */
-export abstract class Repository<RawDataShape = Generic, EntityShape = Generic> {
+export abstract class Repository<RawDataShape = Generic, EntityShape = Generic, M extends DataManager<RawDataShape> = DataManager<RawDataShape>> {
     [property: string]: unknown
 
     public constructor(
-        public readonly driver: DriverAdapter<DataManager<RawDataShape>>
+        public readonly manager: M
     ) {}
 
-    protected abstract transform(data: RawDataShape): EntityShape
+    protected abstract transform(data: RawDataShape, ...args: unknown[]): EntityShape
 } //:: class

package/templates/lib/shared/application/events.ts

@@ -17,7 +17,7 @@ export abstract class Event {
 export abstract class EventHandler {
     [property: string]: unknown
 
-    public abstract handle(event: Event): Promise<void>
+    public abstract handle(event: Event): void
 } //:: class
 
 /**

package/templates/lib/shared/application/http/errors.ts

@@ -2,6 +2,8 @@
  * @description HTTP error with a specific status code and message.
  */
 export class HttpError extends Error {
+    [property: string]: unknown
+
     public static readonly messages: { [code: number]: string } = Object.freeze({
         400: 'Bad Request',
         401: 'Unauthorized',