tshex-cli 1.0.20 → 1.0.21

package/docs/shared/application/validations.md

@@ -0,0 +1,94 @@
+### Validations
+
+Validation objects are responsible for checking whether application input is
+ready for the next step of a process.
+They are used to keep validation explicit before the application constructs
+domain objects or invokes external collaborators.
+
+The generated template provides a single contract for this purpose:
+`Validatable`.
+
+#### Contract
+
+`Validatable` is responsible for exposing a Boolean validation result.
+
+```ts title="shared/application/validations.ts"
+export interface Validatable {
+	isValid(): boolean
+}
+```
+
+This contract stays deliberately small. It does not prescribe how errors are
+stored, how messages are formatted, or whether validation is synchronous or
+composed from several objects.
+
+#### First Validation Object
+
+In the following example we validate a registration payload before the service
+turns it into domain values.
+
+```ts title="users/application/create-user-input.ts"
+import { Validatable } from '../../shared/application/validations.js'
+import { Email } from '../../shared/domain/value-objects.js'
+
+export class CreateUserInput implements Validatable {
+	public constructor(
+		public readonly id: string,
+		public readonly email: string,
+	) {}
+
+	public isValid(): boolean {
+		return this.id.length > 0 && Email.isValid(this.email)
+	}
+}
+```
+
+`CreateUserInput` performs application-level checks without constructing an
+`Email` instance yet. This is useful when the process wants to reject invalid
+input before attempting a full domain conversion.
+
+#### Integration With A Service
+
+Now that the validation object exists, a service can decide what to do when the
+input does not satisfy the contract.
+
+```ts title="users/application/register-user.ts"
+import { Service } from '../../shared/application/services.js'
+import { Validatable } from '../../shared/application/validations.js'
+
+type CreateUserInput = Validatable & {
+	readonly id: string
+	readonly email: string
+}
+
+type RegistrationResult =
+	| { ok: true }
+	| { ok: false; errors: string[] }
+
+export class RegisterUser extends Service {
+	public execute(input: CreateUserInput): RegistrationResult {
+		if (input.isValid() === false) {
+			return {
+				ok: false,
+				errors: ['The registration input is invalid.'],
+			}
+		}
+
+		return {
+			ok: true,
+		}
+	}
+}
+```
+
+The service decides the process outcome, while the validation object owns the
+question of whether the input is acceptable.
+
+> **Hint**
+> `Validatable` does not replace domain rules. Use it for application-level
+> checks. Keep domain invariants inside value objects, entities, or aggregates.
+
+#### Next Step
+
+After validation succeeds, the next step is usually to construct domain objects
+or call a repository through an application service.

package/docs/shared/domain/aggregates.md

@@ -0,0 +1,79 @@
+### Aggregates
+
+An aggregate is responsible for grouping multiple entities into one logical
+domain unit.
+It is used when the behavior of the concept depends on the collaboration of
+several entities instead of a single entity in isolation.
+
+The generated template provides `Aggregate` as a semantic base class.
+
+#### Base Class
+
+`Aggregate` is an abstract class with no concrete methods.
+
+```ts title="shared/domain/aggregates.ts"
+export abstract class Aggregate {}
+```
+
+This means the generated base class does not impose persistence rules, event
+publication, or identity behavior. Those concerns remain in the concrete domain
+model of the project.
+
+#### First Aggregate
+
+In the following example we model a shopping cart as a group of line items.
+
+```ts title="users/domain/cart.ts"
+import { Aggregate } from '../../shared/domain/aggregates.js'
+import { Entity } from '../../shared/domain/entities.js'
+
+class LineItem extends Entity {
+	public constructor(
+		public readonly id: string,
+		public readonly quantity: number,
+	) {
+		super()
+	}
+
+	public equals(other: Entity): boolean {
+		return other instanceof LineItem && this.id === other.id
+	}
+}
+
+export class Cart extends Aggregate {
+	public constructor(public readonly items: Array<LineItem>) {
+		super()
+	}
+
+	public totalItems(): number {
+		return this.items.reduce((sum, item) => sum + item.quantity, 0)
+	}
+}
+```
+
+`Cart` is an aggregate because its behavior depends on the collection of
+entities that compose it. `LineItem` remains an entity because its identity is
+independent inside the aggregate.
+
+#### Responsibility Boundary
+
+An aggregate should own rules that require several internal parts to work
+together.
+
+Examples include:
+
+1. checking whether the aggregate can change status;
+2. keeping related entities in a consistent state;
+3. exposing operations that depend on the collaboration of those entities.
+
+The generated `Aggregate` base class does not implement these rules for you. It
+only provides the semantic place where those rules belong.
+
+> **Warning**
+> Do not extend `Aggregate` only to create a container for unrelated values. Use
+> it when the concept represents one domain unit composed of several parts.
+
+#### Next Step
+
+Aggregates usually collaborate with entities and value objects. The base entity
+behavior is documented in `entities.md`.

package/docs/shared/domain/entities.md

@@ -0,0 +1,91 @@
+### 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.
+
+The generated template provides `Entity` as a base class for this pattern.
+
+#### Base Class
+
+`Entity` requires one operation and already provides two helper methods.
+
+```ts title="shared/domain/entities.ts"
+export abstract class Entity {
+	public abstract equals(other: Entity): boolean
+
+	public toJSON(): Record<string, unknown> {
+		return this
+	}
+
+	public toString(): string {
+		return String(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.
+
+```ts title="users/domain/user.ts"
+import { Entity } from '../../shared/domain/entities.js'
+import { Email } from '../../shared/domain/value-objects.js'
+
+export class User extends Entity {
+	public constructor(
+		public readonly id: string,
+		public readonly email: Email,
+	) {
+		super()
+	}
+
+	public equals(other: Entity): boolean {
+		return other instanceof User && this.id === other.id
+	}
+}
+```
+
+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.
+
+#### Included Behavior
+
+Now that the entity exists, the inherited helpers become useful.
+
+```ts
+const user = new User('usr_1', Email.from('ada@example.com'))
+
+user.toString()
+user.toJSON()
+```
+
+`toString()` returns the constructor name. `toJSON()` returns the instance as a
+plain record, which is convenient for simple serialization or inspection.
+
+#### 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.
+
+> **Hint**
+> Keep `equals()` explicit and small. If the comparison starts depending on many
+> mutable fields, the model may be closer to a value object than to an 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`.

package/docs/shared/domain/errors.md

@@ -0,0 +1,103 @@
+### Errors
+
+Domain errors are responsible for making invalid domain values explicit.
+They are used when a domain concept rejects an input because that input does not
+satisfy the rule required by the concept.
+
+The generated template provides `ValueError` for this purpose.
+
+#### ValueError
+
+`ValueError` is responsible for describing that a received value does not match
+the expected domain concept.
+
+```ts title="shared/domain/errors.ts"
+export class ValueError extends Error {
+	public constructor(received: string, expected: string) {
+		super(`Invalid value ${received} for ${expected}.`)
+	}
+}
+```
+
+The constructor receives the invalid value and the expected concept name. The
+message format is generated automatically.
+
+#### First Usage
+
+In the following example we define a local value object that rejects numbers
+outside the accepted range.
+
+```ts title="users/domain/percentage.ts"
+import { ValueError } from '../../shared/domain/errors.js'
+
+export class Percentage {
+	public constructor(public readonly value: number) {}
+
+	public static from(value: number): Percentage {
+		if (value < 0 || value > 100) {
+			throw new ValueError(String(value), Percentage.name)
+		}
+
+		return new Percentage(value)
+	}
+}
+```
+
+`Percentage.from()` throws `ValueError` when the received value does not satisfy
+the rule of the concept.
+
+#### Handling The Error
+
+Now consider a process that wants to translate a domain error into an
+application-level result.
+
+```ts title="users/application/apply-discount.ts"
+import { ValueError } from '../../shared/domain/errors.js'
+
+type DiscountResult =
+	| { ok: true; value: number }
+	| { ok: false; error: string }
+
+class Percentage {
+	public constructor(public readonly value: number) {}
+
+	public static from(value: number): Percentage {
+		if (value < 0 || value > 100) {
+			throw new ValueError(String(value), Percentage.name)
+		}
+
+		return new Percentage(value)
+	}
+}
+
+export function applyDiscount(value: number): DiscountResult {
+	try {
+		return {
+			ok: true,
+			value: Percentage.from(value).value,
+		}
+	} catch (error: unknown) {
+		if (error instanceof ValueError) {
+			return {
+				ok: false,
+				error: error.message,
+			}
+		}
+
+		throw error
+	}
+}
+```
+
+This pattern keeps the domain rule strict while allowing the application layer
+to decide how that failure is exposed.
+
+> **Hint**
+> `Email.from()` in the generated value objects uses this same error type.
+> Reusing `ValueError` keeps invalid-value failures recognizable across the
+> domain layer.
+
+#### Next Step
+
+The generated value objects that already throw `ValueError` are documented in
+`value-objects.md`.

package/docs/shared/domain/value-objects.md

@@ -0,0 +1,148 @@
+### Value Objects
+
+Value objects are responsible for modeling concepts whose identity is
+determined entirely by their value.
+They are used to keep domain rules, comparisons, and semantics close to the
+data that those rules describe.
+
+The generated template provides the abstract `ValueObject<T>` base class and two
+concrete implementations: `NullableBoolean` and `Email`.
+
+#### Base Class
+
+`ValueObject<T>` is responsible for storing a value and defining its comparison
+rules.
+
+```ts title="shared/domain/value-objects.ts"
+export abstract class ValueObject<T = unknown> {
+	public abstract readonly value: T
+
+	public toString(): string {
+		return String(this.value)
+	}
+
+	public toJSON(): T {
+		return this.value
+	}
+
+	public abstract equals(other: ValueObject<T> | null | undefined): boolean
+
+	public static isValid(value: unknown): boolean {
+		return (
+			value !== null &&
+			value !== undefined &&
+			Object.is(value, NaN) === false
+		)
+	}
+}
+```
+
+The base class provides serialization helpers and a generic validation check.
+Concrete value objects must define `value` and `equals()`.
+
+#### Custom Value Object
+
+In the following example we create a local value object for percentages.
+
+```ts title="users/domain/percentage.ts"
+import { ValueObject } from '../../shared/domain/value-objects.js'
+import { ValueError } from '../../shared/domain/errors.js'
+
+export class Percentage extends ValueObject<number> {
+	public override readonly value: number
+
+	protected constructor(value: number) {
+		super()
+		this.value = value
+	}
+
+	public override equals(
+		other: Percentage | null | undefined,
+	): boolean {
+		if (other === null || other === undefined) {
+			return false
+		}
+
+		return this.value === other.value
+	}
+
+	public static from(value: number): Percentage {
+		if (value < 0 || value > 100) {
+			throw new ValueError(String(value), Percentage.name)
+		}
+
+		return new Percentage(value)
+	}
+}
+```
+
+`Percentage` owns the validation rule of the concept and the equality rule of
+the value. This is the normal responsibility split for a value object.
+
+#### NullableBoolean
+
+`NullableBoolean` is responsible for representing a tri-state Boolean.
+
+```ts title="shared/domain/value-objects.ts"
+import { NullableBoolean } from '../../shared/domain/value-objects.js'
+
+const active = NullableBoolean.from(true)
+const unknown = NullableBoolean.from(null)
+
+active.equals(NullableBoolean.from(true))
+unknown.isIndeterminate()
+```
+
+`from(value)` accepts `true`, `false`, or `null`. `equals()` compares the wrapped
+value. `isIndeterminate()` returns `true` when the state is `null`.
+
+#### Email
+
+`Email` is responsible for validating and describing an email address.
+
+```ts title="shared/domain/value-objects.ts"
+import { Email } from '../../shared/domain/value-objects.js'
+
+const email = Email.from('ada@example.com')
+
+email.username
+email.domain
+email.tld
+```
+
+`Email.from()` validates the string and throws `ValueError` when the input does
+not match the generated email rules. The getters expose common derived parts of
+the address without repeating parsing logic in the rest of the domain.
+
+#### Full Example
+
+The following example combines both generated value objects in one small domain
+shape.
+
+```ts title="users/domain/user-profile.ts"
+import { Email, NullableBoolean } from '../../shared/domain/value-objects.js'
+
+type UserProfile = {
+	email: Email
+	active: NullableBoolean
+}
+
+const profile: UserProfile = {
+	email: Email.from('ada@example.com'),
+	active: NullableBoolean.from(null),
+}
+```
+
+This example keeps the domain data explicit. The email carries its own
+validation and derived fields. The active flag carries its own tri-state
+semantics.
+
+> **Warning**
+> Use a value object only when equality depends on the value itself. If the
+> concept must preserve identity independently from changing attributes, model it
+> as an entity instead.
+
+#### Next Step
+
+After modeling values, the next step is usually to compose them inside entities
+or aggregates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tshex-cli",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "author": "https://github.com/virtualitems/",
   "license": "MIT",
   "description": "Typescript Hexagonal Architecture CLI",
@@ -23,7 +23,11 @@
     "typescript",
     "virtualitems"
   ],
-  "homepage": "https://github.com/virtualitems/tshex-cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/virtualitems/tshex-cli.git"
+  },
+  "homepage": "https://github.com/virtualitems/tshex-cli#readme",
   "bugs": {
     "url": "https://github.com/virtualitems/tshex-cli/issues"
   },
@@ -31,7 +35,8 @@
   "files": [
     "./build",
     "./source",
-    "./templates"
+    "./templates",
+    "./docs"
   ],
   "bin": {
     "tshex": "./build/main.js"