tshex-cli 1.0.19 → 1.0.21

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,7 +1,8 @@
 {
   "name": "tshex-cli",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "author": "https://github.com/virtualitems/",
+  "license": "MIT",
   "description": "Typescript Hexagonal Architecture CLI",
   "type": "module",
   "main": "./build/main.js",
@@ -22,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"
   },
@@ -30,7 +35,8 @@
   "files": [
     "./build",
     "./source",
-    "./templates"
+    "./templates",
+    "./docs"
   ],
   "bin": {
     "tshex": "./build/main.js"