tshex-cli 1.0.29 → 1.0.31

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

@@ -63,21 +63,13 @@ contracts that adapters and services can share.
 #### Shared HTTP Files
 
 The `shared/application/http` directory groups the framework-agnostic HTTP
-boundary and the type-only specifications for common web content formats.
+boundary contracts.
 
 | File | Responsibility |
 | --- | --- |
-| `shared/application/http/handlers.ts` | Declares `HttpRequestHandler` and `HttpMiddleware`. |
 | `shared/application/http/errors.ts` | Declares `HttpError`. |
-| `shared/application/http/json-api.ts` | Type-only JSON:API v1.1 document, resource, and Atomic Operations declarations. |
-| `shared/application/http/json-web-token.ts` | Type-only JOSE/JWT declarations (JWK, JWS, JWE, JWT claims). |
-| `shared/application/http/opengraph.ts` | Type-only Open Graph, Twitter Card, and social metadata declarations. |
 
-`handlers.ts` and `errors.ts` are the only files in this directory with
-runtime code. `json-api.ts`, `json-web-token.ts`, and `opengraph.ts` contain
-compile-time structure only; they describe the shape of external formats
-without implementing parsing, validation, or serialization. Each file is
-documented in its own page under `shared/application/http/*.md`.
+`errors.ts` is documented in its own page under `shared/application/http/errors.md`.
 
 #### Shared Data Files
 
@@ -85,8 +77,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,23 @@ 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'
+import { Email } from './shared/domain/value-objects.ts'
+
+const example = new Example()
+const student = new Student('Ada Lovelace', Email.from('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,260 @@
 ### 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'
+import { Email } from '../shared/domain/value-objects.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, Email.from(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 +263,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