tshex-cli 1.0.28 → 1.0.30

package/docs/shared/application/data.md

@@ -1,176 +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
+}
 
-    public abstract all(): Promise<Array<T>>
+export abstract class DatasetManager<T = Record<string, unknown>> extends DataManager<T> {
+    [property: string]: unknown
+
+    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`.
 
-#### First Implementation
+#### Driver Adapter
 
-In the following example we implement an in-memory manager and its driver.
+`DriverAdapter` is responsible for connecting to a data source and returning an
+enabled `DataManager`.
 
-```ts title="users/adapters/memory-users-driver.ts"
-import { DriverAdapter } from '../../shared/application/data/drivers.js'
-import { DataManager } from '../../shared/application/data/managers.js'
+```ts title="shared/application/data/drivers.ts"
+export abstract class DriverAdapter<M extends DataManager = DataManager> {
+    [property: string]: unknown
 
-type UserRecord = {
-    id: string
-    email: string
-    active: boolean | null
+    public abstract connect(...args: unknown[]): M
+
+    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 type Database = Record<string, Generic[]>
+
+export class InMemoryDatabaseDriver extends DriverAdapter<InMemoryDatabaseManager> {
+    [property: string]: unknown
 
-export class MemoryUsersDriver extends DriverAdapter<MemoryUsersManager> {
-    public constructor(private readonly rows: Array<UserRecord>) {
+    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.
 
 #### Repository
 
 `Repository` is responsible for transforming raw records into domain-oriented
-representations.
+representations. It holds a reference to the manager and requires `transform()`
+to map a raw record into a domain entity.
 
 ```ts title="shared/application/data/repositories.ts"
-import { type DataManager } from './managers.js'
-import { type DriverAdapter } from './drivers.js'
-
 export abstract class Repository<
-    DataShape extends Record<string, unknown> = Record<string, unknown>,
-    EntityShape extends Record<string, unknown> = Record<string, unknown>
+    RawDataShape = Generic,
+    EntityShape = Generic,
+    M extends DataManager<RawDataShape> = DataManager<RawDataShape>
 > {
-    public constructor(public readonly driver: DriverAdapter<DataManager<DataShape>>) {}
+    [property: string]: unknown
 
-    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
+    public constructor(public readonly manager: M) {}
+
+    protected abstract transform(data: RawDataShape, ...args: unknown[]): EntityShape
+}
+```
+
+Data retrieval operations are not defined in the base class — add them
+explicitly in the concrete class using the capability interfaces from
+`capabilities.ts`.
+
+```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'
+
+export class CoursesRepository extends Repository<CourseData, Course, InMemoryDatabaseManager> {
+    [property: string]: unknown
+
+    constructor(manager: InMemoryDatabaseManager) {
+        super(manager)
     }
 
-    protected transformList(data: Array<DataShape>): Array<EntityShape> {
-        return data.map(this.transform)
+    protected transform(data: CourseData): Course {
+        return new Course(data.name, data.description, data.duration_hours)
     }
 
-    protected abstract transform(data: DataShape): EntityShape
+    public create(course: Course): boolean {
+        return this.manager.create(course.toJSON())
+    }
+
+    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
 
@@ -179,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