tshex-cli 1.0.28 → 1.0.30

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.28",
+  "version": "1.0.30",
   "author": "https://github.com/virtualitems/",
   "license": "MIT",
   "description": "Typescript Hexagonal Architecture CLI",
@@ -41,15 +41,14 @@
   "bin": {
     "tshex": "./build/main.js"
   },
+  "scripts": {
+    "build": "deno run --allow-all npm:esbuild --bundle --minify --platform=node --external:commander --format=esm --outfile=./build/main.js ./source/main.ts",
+    "test": "deno test --allow-all tests/"
+  },
   "dependencies": {
-    "commander": "^12.1.0"
+    "commander": "^15.0.0"
   },
   "devDependencies": {
-    "@fission-ai/openspec": "^1.6.0",
-    "@types/node": "^22.5.4",
-    "typescript": "^5.4.5"
-  },
-  "scripts": {
-    "build": "tsc"
+    "@types/node": "^18"
   }
 }

package/source/main.ts

@@ -9,12 +9,12 @@ import { program } from 'commander'
 import fs from 'node:fs'
 import path from 'node:path'
 import readline from 'node:readline/promises'
-import { stdin as input, stdout as output } from 'node:process'
+import { stdin, stdout } from 'node:process'
 
 // FUNCTIONS
 
 function readPackageJson() {
-    const filePath = path.join(import.meta.dirname, '..', 'package.json')
+    const filePath = path.join(import.meta.dirname!, '..', 'package.json')
     const fileContents = fs.readFileSync(filePath, 'utf-8')
     return JSON.parse(fileContents)
 }
@@ -77,19 +77,35 @@ function executeCreateTests(
                 continue
             }
 
-            if (ignoredSourceDir !== undefined && sourcePath.startsWith(ignoredSourceDir)) {
+            if (
+                ignoredSourceDir !== undefined &&
+                sourcePath.startsWith(ignoredSourceDir)
+            ) {
                 continue
             }
 
-            if (fs.existsSync(destinationPath) && fs.statSync(destinationPath).isDirectory() === false) {
+            if (
+                fs.existsSync(destinationPath) &&
+                fs.statSync(destinationPath).isDirectory() === false
+            ) {
                 continue
             }
 
-            executeCreateTests(sourcePath, destinationPath, fileContents, ignoredSourceDir, rootSourceDir)
+            executeCreateTests(
+                sourcePath,
+                destinationPath,
+                fileContents,
+                ignoredSourceDir,
+                rootSourceDir
+            )
             continue
         }
 
-        if (entry.isFile() && entry.name.endsWith('.ts') && fs.existsSync(destinationPath) === false) {
+        if (
+            entry.isFile() &&
+            entry.name.endsWith('.ts') &&
+            fs.existsSync(destinationPath) === false
+        ) {
             fs.writeFileSync(destinationPath, fileContents)
         }
     }
@@ -104,10 +120,12 @@ async function ensureTestsDirectory(testsRootDir: string) {
         return
     }
 
-    const rl = readline.createInterface({ input, output })
+    const rl = readline.createInterface({ input: stdin, output: stdout })
 
     try {
-        const answer = await rl.question(`Tests directory does not exist at ${testsRootDir}. Create it? (y/N) `)
+        const answer = await rl.question(
+            `Tests directory does not exist at ${testsRootDir}. Create it? (y/N) `
+        )
 
         if (answer.trim().toLowerCase() !== 'y') {
             return false
@@ -121,7 +139,7 @@ async function ensureTestsDirectory(testsRootDir: string) {
 }
 
 async function main(program: typeof import('commander').program) {
-    const templatesDir = path.join(import.meta.dirname, '..', 'templates')
+    const templatesDir = path.join(import.meta.dirname!, '..', 'templates')
 
     const options = program.opts()
 
@@ -182,7 +200,9 @@ async function main(program: typeof import('commander').program) {
         const testsDir = path.join(testsRootDir, path.basename(sourceDir))
 
         if (testsDir === sourceDir) {
-            program.error('Tests destination directory cannot be the same as the source directory')
+            program.error(
+                'Tests destination directory cannot be the same as the source directory'
+            )
         }
 
         executeCreateTests(sourceDir, testsDir, testsTemplateContents, testsRootDir)
@@ -198,7 +218,10 @@ program
     .option('-P, --project <name>', "creates a new project with it's shared directory")
     .option('-C, --context <name>', 'creates a new context')
     .option('-R, --react', 'creates a React context with --context')
-    .option('-T, --tests <path>', 'creates a .ts tests structure from an existing directory')
+    .option(
+        '-T, --tests <path>',
+        'creates a .ts tests structure from an existing directory'
+    )
     .option('--dir <path>', 'sets the directory to create the new item')
     .parse(process.argv)
 

package/templates/ctx/example-ports.ts

@@ -1,4 +1,5 @@
 // Ports are exports from the context root level
+// you can delete this file and create your own ports file in the context root level
 
 export function example(): void {
     // ...

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

@@ -0,0 +1,60 @@
+type Generic = Record<string, unknown>
+
+export interface Listable<DataShape extends Generic = Generic> {
+    all(): DataShape[]
+}
+
+/**
+ * @description Declares a filtering operation over plain source records.
+ */
+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<DataShape extends Generic = Generic, Selector = unknown> {
+    sort(selector: Selector): DataShape[]
+}
+
+/**
+ * @description Declares a creation operation for plain source records.
+ */
+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<
+    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<Selector = unknown, Feedback = unknown> {
+    delete(selector: Selector): Feedback
+}
+
+/**
+ * @description Declares an aggregation operation over source records.
+ */
+export interface Aggregatable<Selector = unknown, Feedback = unknown> {
+    aggregate(selector: Selector): Feedback
+}
+
+/**
+ * @description Declares operations for selecting or preloading relationships from a data source.
+ */
+export interface Relatable {
+    selectRelated(...args: unknown[]): unknown
+
+    prefetchRelated(...args: unknown[]): unknown
+}

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

@@ -1,66 +1,9 @@
-/**
- * @description Declares a filtering operation over plain source records.
- */
-export interface Filterable<S = Record<string, unknown>> {
-    filter(selector: S): Promise<Array<S>>
-}
-
-/**
- * @description Declares a sorting operation over plain source records.
- */
-export interface Sortable<S = Record<string, unknown>> {
-    sort(selector: S): Promise<Array<S>>
-}
-
-/**
- * @description Declares a creation operation for plain source records.
- */
-export interface Creatable<D = Record<string, unknown>> {
-    create(data: D): Promise<unknown>
-}
-
-/**
- * @description Declares an update operation that selects source records and applies new plain data.
- */
-export interface Updatable<S = Record<string, unknown>, D = Record<string, unknown>> {
-    update(selector: S, data: D): Promise<unknown>
-}
-
-/**
- * @description Declares a deletion operation over source records selected by plain criteria.
- */
-export interface Deletable<S = Record<string, unknown>> {
-    delete(selector: S): Promise<unknown>
-}
-
-/**
- * @description Declares an aggregation operation over source records.
- */
-export interface Aggregatable<S = Record<string, unknown>> {
-    aggregate(selector: S): Promise<S>
-}
-
-/**
- * @description Declares operations for selecting or preloading relationships from a data source.
- */
-export interface Relatable {
-    selectRelated(...args: unknown[]): unknown
-
-    prefetchRelated(...args: unknown[]): unknown
-}
-
 /**
  * @description Operates on a data source using plain objects and arrays.
  * It exposes the raw data without transforming it.
  */
 export abstract class DataManager<T = Record<string, unknown>> {
     [property: string]: unknown
-
-    public none(): Array<T> {
-        return []
-    }
-
-    public abstract all(): Promise<Array<T>>
 } //:: class
 
 /**
@@ -69,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