tshex-cli 1.0.29 → 1.0.31

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,121 @@ 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'
+import { Email } from '../shared/domain/value-objects.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: Email
+    ) {
+        super()
+    }
 
-Now that the entity exists, the inherited helpers become useful.
+    public equals(other: Student): boolean {
+        return this.email.equals(other.email)
+    }
 
-```ts
-const user = new User('usr_1', Email.from('ada@example.com'))
+    public override toJSON() {
+        return {
+            name: this.name,
+            email: this.email.value
+        }
+    }
+}
+```
 
-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
+address represent the same person. `equals()` delegates to `Email.equals()` so
+the comparison rule lives in the value object. `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 +135,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.31",
   "author": "https://github.com/virtualitems/",
   "license": "MIT",
   "description": "Typescript Hexagonal Architecture CLI",

package/readme.md

@@ -86,16 +86,13 @@ core/
 |-- shared/
 |   |-- application/
 |   |   |-- data/
+|   |   |   |-- capabilities.ts
 |   |   |   |-- drivers.ts
 |   |   |   |-- managers.ts
 |   |   |   `-- repositories.ts
 |   |   |-- events.ts
 |   |   |-- http/
-|   |   |   |-- errors.ts
-|   |   |   |-- handlers.ts
-|   |   |   |-- json-api.ts
-|   |   |   |-- json-web-token.ts
-|   |   |   `-- opengraph.ts
+|   |   |   `-- errors.ts
 |   |   |-- loggers.ts
 |   |   |-- services.ts
 |   |   `-- validations.ts
@@ -248,10 +245,6 @@ From this point on, the guide is split into dedicated documents under `docs/`.
 - [shared/application/data](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/data.md)
 - [shared/application/events.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/events.md)
 - [shared/application/http/errors.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/errors.md)
-- [shared/application/http/handlers.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/handlers.md)
-- [shared/application/http/json-api.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/json-api.md)
-- [shared/application/http/json-web-token.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/json-web-token.md)
-- [shared/application/http/opengraph.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/opengraph.md)
 - [shared/application/loggers.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/loggers.md)
 - [shared/application/services.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/services.md)
 - [shared/application/validations.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/validations.md)

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
 }
 
 /**