ddd-ts-kit 0.2.0 → 0.3.0

package/templates/docs/openapi.json.tpl

@@ -328,6 +328,11 @@
               }
             }
           },
+          "facts": {
+            "type": "object",
+            "description": "The facts of the refusal its code exposes, by name. Absent when it exposes none.",
+            "additionalProperties": true
+          },
           "requestId": {
             "type": "string"
           }

package/templates/entity/entity.ts.tpl

@@ -13,7 +13,12 @@ export class {{name.pascal}} extends Entity<string> {
   }
 
   static create(id: string, state: {{name.pascal}}State): {{name.pascal}} {
+{{#if refusals.factories}}
+    // TODO(domain): check the invariants {{name.pascal}} guards on its own and throw a refusal of the error class of its aggregate when one is violated (`ddd-ts-kit generate error {{context.kebab}} <Concept> <refusal>`); invariants spanning several entities belong to the aggregate root.
+{{/if}}
+{{#if refusals.classes}}
     // TODO(domain): check the invariants {{name.pascal}} guards on its own and throw a DomainError of ../errors when one is violated; invariants spanning several entities belong to the aggregate root.
+{{/if}}
     return new {{name.pascal}}(id, state);
   }
 

package/templates/error/case.spec.ts.tpl

@@ -0,0 +1,8 @@
+  it('refuses "{{refusal.words}}" with the code {{error.code}}', () => {
+    const error = {{name.pascal}}Error.{{refusal.camel}}();
+
+    expect(error).toBeInstanceOf(DomainError);
+    expect(error.code).toBe('{{error.code}}');
+    expect(error.message).toBe('{{refusal.title}}.');
+    expect(error.facts).toEqual({});
+  });

package/templates/error/concept-error.spec.ts.tpl

@@ -0,0 +1,7 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { DomainError } from '@ddd-ts-kit/kernel';
+import { {{name.pascal}}Error } from '{{alias.context}}/domain/errors/{{name.kebab}}.error{{alias.ext}}';
+
+describe('{{name.pascal}}Error', () => {
+{{error.case}}
+});

package/templates/error/concept-error.ts.tpl

@@ -0,0 +1,5 @@
+import { ConceptError } from '@ddd-ts-kit/kernel';
+
+export class {{name.pascal}}Error extends ConceptError {
+{{error.factory}}
+}

package/templates/error/factory.ts.tpl

@@ -0,0 +1,4 @@
+  static {{refusal.camel}}() {
+    // TODO(domain): take as parameters the facts that explain this refusal (which {{context.words}} rule, which value), give them as the third argument and write a message a domain expert would recognise; a fact reaches the client only when named: `.exposing('<fact>')`. The code is the stable contract.
+    return {{name.pascal}}Error.refusal('{{error.code}}', '{{refusal.title}}.');
+  }

package/templates/init/jest.config.js.tpl

@@ -16,7 +16,14 @@ export default {
       {
         jsc: {
           parser: { syntax: 'typescript', decorators: true },
+{{#if decorators.legacy}}
+          // A library of the stack only has legacy decorators: the whole program is compiled in that mode, with the metadata it reads.
           transform: { legacyDecorator: true, decoratorMetadata: true },
+{{/if}}
+{{#if decorators.standard}}
+          // Standard decorators, as `tsc` emits them for this project: no `experimentalDecorators` in tsconfig.json.
+          transform: { decoratorVersion: '2022-03' },
+{{/if}}
           target: 'es2022',
         },
       },

package/templates/init/rules/domain.md.tpl

@@ -10,9 +10,20 @@ paths:
 - Names come from the glossary of `CONTEXT.md`, written first (`language/glossary-term`); no `Manager`, `Helper`, `Data`, `Info`, `Model` (`language/no-technical-name`).
 - Aggregate: private constructor, `create` for birth, `rehydrate` for loading, state changed by methods named after the business intention, no setter, no public mutable property (`domain/aggregate-encapsulation`). One aggregate per transaction; another one is referenced by its id.
 - Value objects are immutable, validated in `create`, compared with `equals` (`domain/value-object-immutability`). An email, an amount, a period are types, not strings.
+{{#if refusals.factories}}
+- A violated invariant throws a refusal built by a static factory of the error class of its concept, never `new` and never a bare `Error`: `throw InvoiceError.alreadyIssued(this.id)` (`errors/through-factory`, `domain/no-generic-error`). One class per concept of the glossary in `domain/errors/`, extending `ConceptError`, no constructor (`errors/constructor-not-public`); a factory is named after the refusal and its code says the same words (`errors/factory-name`), one code per refusal of the context (`errors/code-unique`).
+- A factory takes the facts of the refusal as typed parameters and gives them to `refusal(code, message, facts)`. Facts are private: one reaches a client only when the factory names it, `.exposing('<fact>')`, and never when it identifies a person. A value object returns its refusals in the `Result` of `create`: `err(PersonError.invalidEmail(raw))`.
+{{/if}}
+{{#if refusals.classes}}
 - A violated invariant throws a `DomainError` of `domain/errors/` with a stable `code`, never a bare `Error` (`domain/no-generic-error`).
+{{/if}}
 - Domain events are named in the past tense, `<context>.<aggregate>.<fact>` (`events/name-format`), and recorded by the aggregate (`this.record(...)`). They leave with the save: nothing here dispatches them.
 - A repository here is a port: an abstract class extending the kernel `Repository<Aggregate>`, abstract members only (`ports/abstract-class`). A domain service is stateless.
 - Time and identifiers come in as parameters (`purity/*`); nothing here knows the acting user or its rights (`authz/in-application`).
 - One concept per file, with the suffix of its role: `.aggregate.ts`, `.entity.ts`, `.vo.ts`, `.event.ts`, `.error.ts`, `.repository.ts`, `.service.ts` (`naming/suffix`, `naming/one-concept-per-file`).
+{{#if refusals.factories}}
+- The language first, with `/ddd-ts-kit:glossary`. Then create with `npx ddd-ts-kit generate aggregate|entity|value-object|domain-event|domain-service|repository ... --json`, a refusal with `npx ddd-ts-kit generate error <context> <Concept> <refusal> --json` (it adds the factory to the class of the concept, and its case to the spec), and fill the `TODO(domain)` places it lists.
+{{/if}}
+{{#if refusals.classes}}
 - The language first, with `/ddd-ts-kit:glossary`. Then create with `npx ddd-ts-kit generate aggregate|entity|value-object|domain-event|domain-error|domain-service|repository ... --json` and fill the `TODO(domain)` places it lists.
+{{/if}}

package/templates/init/rules/presentation.md.tpl

@@ -10,7 +10,12 @@ paths:
 - A route validates the shape of the input, builds a command or a query with the actor, executes it through `CommandBus` or `QueryBus` (never a handler class) and maps the answer. Nothing else.
 - Imports `application/` (and domain types for mapping), never `infrastructure/` (`layer/presentation-no-infrastructure`).
 - Input shape is validated here with the schema library of the project, behind the `Schema` port. Business rules are not validated here.
+{{#if refusals.factories}}
+- Every route declares its `security`, or `security: false`, and the codes of the refusals it can answer in `errors`, as their factories set them (`errors/known-code`); the mapping from code to status lives in one place, the error mapper. A client reads the `code`, and under `facts` only what a factory exposed.
+{{/if}}
+{{#if refusals.classes}}
 - Every route declares its `security`, or `security: false`, and the `DomainError` codes it can answer in `errors`; the mapping from code to status lives in one place, the error mapper.
+{{/if}}
 - No role or ownership test here (`authz/in-application`): the bus asks for the permission, a policy decides on loaded state.
 - Request and response types are presentation types (`*.dto.ts`): never an aggregate, never a row.
 - Never put the message of an unexpected failure in a response or a log.

package/templates/pipeline/package-scripts.json

@@ -23,7 +23,7 @@
     "@biomejs/biome": "2.5.15",
     "@commitlint/cli": "^21.2.3",
     "@commitlint/config-conventional": "^21.2.3",
-    "@ddd-ts-kit/eslint-plugin": "^0.2.0",
+    "@ddd-ts-kit/eslint-plugin": "^0.3.0",
     "@eslint/js": "^10.0.1",
     "@typescript/native": "npm:typescript@~7.0.2",
     "@vitest/coverage-v8": "5.0.3",

package/templates/route/route.class-validator.ts.tpl

@@ -42,7 +42,7 @@ export function {{name.camel}}Route({{route.bus}}: {{route.busType}}): Route {
       {{#if route.isQuery}}
       responses: { {{route.status}}: { description: 'The answer.', body: answer } },
       {{/if}}
-      // TODO(domain): list the codes of the DomainErrors "{{name.words}}" can raise, so that they appear in the contract with their status.
+      // TODO(domain): list the codes of the refusals "{{name.words}}" can raise, as their factories set them, so that they appear in the contract with their status (`errors/known-code`).
       errors: [{{route.errorCodes}}],
       security: {{route.security}},
     },

package/templates/route/route.none.ts.tpl

@@ -61,7 +61,7 @@ export function {{name.camel}}Route({{route.bus}}: {{route.busType}}): Route {
       {{#if route.isQuery}}
       responses: { {{route.status}}: { description: 'The answer.', body: answer } },
       {{/if}}
-      // TODO(domain): list the codes of the DomainErrors "{{name.words}}" can raise, so that they appear in the contract with their status.
+      // TODO(domain): list the codes of the refusals "{{name.words}}" can raise, as their factories set them, so that they appear in the contract with their status (`errors/known-code`).
       errors: [{{route.errorCodes}}],
       security: {{route.security}},
     },

package/templates/route/route.search.ts.tpl

@@ -62,7 +62,7 @@ export function {{name.camel}}Route(queries: QueryBus): Route {
       tags: ['{{context.kebab}}'],
       request: { query },
       responses: { 200: { description: 'One page of the search.', body: pageSchemaOf(line) } },
-      // TODO(domain): list the codes of the DomainErrors "{{name.words}}" can raise, so that they appear in the contract with their status.
+      // TODO(domain): list the codes of the refusals "{{name.words}}" can raise, as their factories set them, so that they appear in the contract with their status (`errors/known-code`).
       errors: ['UNAUTHORIZED', 'FORBIDDEN'],
       security: {{route.security}},
     },

package/templates/route/route.standard-schema.ts.tpl

@@ -70,7 +70,7 @@ export function {{name.camel}}Route({{route.bus}}: {{route.busType}}): Route {
       {{#if route.isQuery}}
       responses: { {{route.status}}: { description: 'The answer.', body: answer } },
       {{/if}}
-      // TODO(domain): list the codes of the DomainErrors "{{name.words}}" can raise, so that they appear in the contract with their status.
+      // TODO(domain): list the codes of the refusals "{{name.words}}" can raise, as their factories set them, so that they appear in the contract with their status (`errors/known-code`).
       errors: [{{route.errorCodes}}],
       security: {{route.security}},
     },

package/templates/route/route.zod.ts.tpl

@@ -52,7 +52,7 @@ export function {{name.camel}}Route({{route.bus}}: {{route.busType}}): Route {
       {{#if route.isQuery}}
       responses: { {{route.status}}: { description: 'The answer.', body: answer } },
       {{/if}}
-      // TODO(domain): list the codes of the DomainErrors "{{name.words}}" can raise, so that they appear in the contract with their status.
+      // TODO(domain): list the codes of the refusals "{{name.words}}" can raise, as their factories set them, so that they appear in the contract with their status (`errors/known-code`).
       errors: [{{route.errorCodes}}],
       security: {{route.security}},
     },

package/templates/value-object/value-object.ts.tpl

@@ -10,7 +10,12 @@ export class {{name.pascal}} extends ValueObject<{{name.pascal}}Props> {
   }
 
   static create(value: string): Result<{{name.pascal}}, InvariantViolation> {
+{{#if refusals.factories}}
+    // TODO(domain): replace `value: string` by the real components of {{name.pascal}}, normalize them and check every validity rule; return `err(...)` with a refusal of the concept this value describes, for example `<Concept>Error.invalid{{name.pascal}}(value)` (`ddd-ts-kit generate error {{context.kebab}} <Concept> invalid{{name.pascal}}`), instead of InvariantViolation.
+{{/if}}
+{{#if refusals.classes}}
     // TODO(domain): replace `value: string` by the real components of {{name.pascal}}, normalize them and check every validity rule; return `err(...)` with a dedicated error (`ddd-ts-kit generate domain-error {{context.kebab}} Invalid{{name.pascal}}`) instead of InvariantViolation.
+{{/if}}
     if (value.trim().length === 0) {
       return err(new InvariantViolation('{{name.title}} must not be empty.'));
     }