@domain-first/project-structure 6.0.0 → 7.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -19
- package/dist/201.js +46 -35
- package/dist/287.js +1685 -1612
- package/dist/config-file.d.ts +2 -2
- package/dist/dependency-rules.d.ts +1 -1
- package/dist/file-system.d.ts +5 -0
- package/dist/in-memory-db.d.ts +5 -0
- package/dist/index.cjs +100 -916
- package/dist/index.js +6 -46
- package/dist/init.cjs +868 -0
- package/dist/init.d.ts +2 -0
- package/dist/init.js +36 -0
- package/dist/integration.cjs +412 -33
- package/dist/integration.js +4 -4
- package/dist/integrations/in-memory-db.d.ts +6 -0
- package/dist/integrations/index.d.ts +2 -0
- package/dist/integrations/missing-domain-first-packages.d.ts +8 -0
- package/dist/integrations/rest-endpoint-generator.d.ts +18 -0
- package/dist/integrations/rest-endpoint-generator.spec.d.ts +1 -0
- package/dist/lint.cjs +8 -8
- package/dist/lint.js +7 -7
- package/dist/print-next-steps.d.ts +2 -2
- package/dist/react.cjs +915 -0
- package/dist/react.d.ts +2 -0
- package/dist/react.js +73 -0
- package/dist/use-cases/rest-endpoint-generator.d.ts +1 -1
- package/package.json +3 -1
- package/skills/df-ps-implement/SKILL.md +10 -55
- package/skills/df-ps-plan-feature/SKILL.md +6 -6
- package/skills/df-ps-project-scripts/SKILL.md +1 -1
- package/skills/df-ps-react/SKILL.md +82 -0
- package/skills/df-ps-react/references/generators.md +80 -0
- package/skills/df-ps-scaffold/SKILL.md +38 -20
- package/skills/df-ps-scaffold/references/choosing-components.md +7 -28
- package/skills/df-ps-scaffold/references/generators.md +6 -179
- package/skills/df-ps-scaffold/references/units/aggregate.md +47 -0
- package/skills/df-ps-scaffold/references/units/bounded-context.md +13 -0
- package/skills/df-ps-scaffold/references/units/command-query.md +32 -0
- package/skills/df-ps-scaffold/references/units/endpoint.md +28 -0
- package/skills/df-ps-scaffold/references/units/entity-value-object.md +27 -0
- package/skills/df-ps-scaffold/references/units/errors.md +26 -0
- package/skills/df-ps-scaffold/references/units/port.md +23 -0
- package/skills/df-ps-scaffold/references/units/services.md +28 -0
- package/skills/df-ps-scaffold/references/units/use-case.md +25 -0
- package/skills/df-ps-scaffold/references/units/wire-dependency.md +15 -0
- package/skills/df-ps-scaffold/scripts/drive.mjs +12 -4
|
@@ -10,10 +10,10 @@ Split the request into pieces of logic (one responsibility each). For each piece
|
|
|
10
10
|
| --- | --- | --- |
|
|
11
11
|
| 1 | A business failure callers must recognize? | **Errors** (Domain → Errors) |
|
|
12
12
|
| 2 | An HTTP entry point? | **REST endpoint** (Presentation; needs handlers-rest) |
|
|
13
|
-
| 3 | A screen, UI block, or app-wide React hook? | **React page / widget / UI-kit component / shared hook**. Which one
|
|
13
|
+
| 3 | A screen, UI block, or app-wide React hook? | **React page / widget / UI-kit component / shared hook**. Which one: `df-ps-react` |
|
|
14
14
|
| 4 | A thing with identity, lifecycle, and rules about its own state, **owned by this context** and stored on its own? | **Aggregate** (+ repository) |
|
|
15
15
|
| 5 | An entity or value object used **only inside one** aggregate (an entity inside it, or a value like `order-id` used only by `order`)? | **Entity / value object** (Domain → New Entity / New Value Object, pick that aggregate) |
|
|
16
|
-
| 6 | An entity or value object used by **several** aggregates or by a domain service? | **Entity / value object** (Domain → New Entity / New Value Object, `No aggregate`). Universal ones (see "Where it goes") in Shared
|
|
16
|
+
| 6 | An entity or value object used by **several** aggregates or by a domain service? | **Entity / value object** (Domain → New Entity / New Value Object, `No aggregate`). Universal ones (see "Where it goes") in Shared Kernel |
|
|
17
17
|
| 7 | A rule about one aggregate's own state, including the junction of entities / value objects that all belong to it? | **Method on the aggregate**. No new file |
|
|
18
18
|
| 8 | One business action a user/system triggers that doesn't fit into a single query or command? (Its I/O is separate pieces.) | **Use case**. An action that is exactly one query or command gets none (see below) |
|
|
19
19
|
| 9 | Data or behavior of **another context**? | **Query** (read) / **command** (write) in this context, one per atomic operation (see below) |
|
|
@@ -27,7 +27,7 @@ Split the request into pieces of logic (one responsibility each). For each piece
|
|
|
27
27
|
|
|
28
28
|
- Entities and value objects are **rich**: rules about their own data, including how they are created, are their methods. They never know about their storage or loading: that's repositories and queries/commands.
|
|
29
29
|
- Loading/saving one aggregate = a **repository method**, not a query or command.
|
|
30
|
-
- A query or command is **one atomic operation of one kind of implementation**: one database operation (several statements in one transaction count as one), one request to
|
|
30
|
+
- A query or command is **one atomic operation of one kind of implementation**: one database operation (several statements in one transaction count as one), one request to another context's endpoint, one message sent to another context (an external API is never a query or command: it's a port). Its implementations differ only in how they perform that operation (`prisma`, `http`, `in-memory`). Several operations, a mix of storages, or logic between the steps → several queries/commands, composed in the use case that needs them; only when 2+ use cases need the same composition does it move to an application service (step 13).
|
|
31
31
|
- **No proxy use cases.** Every query and command is a handler, so an endpoint uses it directly. A use case that only forwards the call to one query or command adds nothing: don't create it. A use case appears only when the action needs several queries, commands or ports, or logic around them. A use case whose logic lives in an application service is not a proxy: an application service has no `handle`, so the use case is how an endpoint reaches that logic.
|
|
32
32
|
- A rule about a **set** of aggregates (uniqueness, "at most N per day") = a repository method that queries it, plus a check and a domain error in the use case. No separate component.
|
|
33
33
|
- Steps 9–10 beat 11–15. The other-context or external part becomes a query/command or a port. What remains may be a service that **receives it in its constructor**.
|
|
@@ -48,40 +48,19 @@ Example: `order-confirmation` prepares a message and calls the injected `mailer`
|
|
|
48
48
|
| --- | --- |
|
|
49
49
|
| Port / repository | Own aggregate's persistence → repository. External system → port. |
|
|
50
50
|
| Port / command, query | Own storage or another context → command/query. External system → port. |
|
|
51
|
+
| Port with one method / query | Decided by what's on the other side, not by the number of methods: a single read from an external system is still a port. Another context = a folder in `bounded-contexts/` of this project; any other service (another team's API, a SaaS) is an external system → port. |
|
|
51
52
|
| Query / command | A query only reads: it never changes any state, not even idempotently (no cache filling, no default settings created if missing), and never calls a command. Any state change → command. A command returns nothing or only the minimum needed to use its result later (the created order's ID), never the changed data: read that with a query. A command or query implementation depends only on infrastructure services (the database client, the HTTP client it runs on) and uses domain models; no repositories, ports, domain services or other commands and queries. Composing them is the job of a use case or an application service. |
|
|
52
53
|
| Domain service / entity, value object method | One entity / value object → its method. The junction of several → always a domain service, unless they all belong to one aggregate → a method on that aggregate. |
|
|
53
54
|
| Domain / application service | Stated without requests, permissions, responses, scenarios → domain. Otherwise application. |
|
|
54
55
|
| Use case / application service | Use case = one action with `handle`, the entry point an endpoint calls. Application service = helper with no `handle`, used by 2+ use cases. A composition of queries/commands needed by one action stays in its use case; the same composition needed by several → application service, called by each of those use cases. |
|
|
55
56
|
| Application / infrastructure service | Used by use cases → application. Only by adapters/repositories → infrastructure. |
|
|
56
57
|
| Logic infrastructure needs from an application service | Infrastructure never sees application services. Pure logic without ports → domain service. Logic over ports → infrastructure calls the ports directly. Technical (mapping, retries, external API formats) → infrastructure service. |
|
|
57
|
-
| Clock | Always a port (`clock`, usually in Shared
|
|
58
|
-
|
|
59
|
-
## React page, widget, UI-kit component or shared hook
|
|
60
|
-
|
|
61
|
-
| Piece | Component |
|
|
62
|
-
| --- | --- |
|
|
63
|
-
| A route / whole screen | **Page** |
|
|
64
|
-
| A block with business meaning or backend data (`cart`, `order-summary`) | **Widget** |
|
|
65
|
-
| A generic element with no business meaning, driven only by props (`button`, `date-picker`, `modal`) | **UI-kit component** |
|
|
66
|
-
| A business element that several widgets repeat whole, with the same meaning (`product-card`) | **UI-kit component** (domain) |
|
|
67
|
-
| Generic app-wide logic without markup and business meaning (`debounce`, `media-query`, `local-storage`) | **Shared hook** |
|
|
68
|
-
|
|
69
|
-
A UI-kit component or shared hook that starts needing data (API client, loading, backend state) becomes a widget that uses it. A widget's own state goes in its `hooks/`, not in a shared hook.
|
|
70
|
-
|
|
71
|
-
A business element goes to UI-kit only when several widgets contain the same element, repeated whole and with the same meaning (a product card shown in a catalog, a cart and recommendations). It stays presentational: business data comes in through props, actions go out through callbacks; no API client, no data loading, no imports from widgets, pages or bounded contexts. Its props describe what it shows (`title`, `price`), not domain types. One widget needing it, or several widgets sharing only a piece of markup, is not a reason: keep it in the widget, or extract the generic piece as a generic UI-kit component.
|
|
72
|
-
|
|
73
|
-
**Widgets never import each other.** Not a widget, not its `ui/`, `hooks/` or `types.ts`. What two widgets share goes to UI-kit (an element, by the rules above) or a shared hook (logic without markup); combining widgets is the page's job.
|
|
74
|
-
|
|
75
|
-
Nest a page or widget name in folders (`admin/users`) when it belongs to an area of the UI with several pages or widgets: a route group (`/admin/*`) or one section of a screen. Pages follow the route path; a widget goes under the area it serves. Otherwise keep the name flat (`order-summary`); one page or widget is no reason to start a folder. The whole path becomes the code name, so it must read as the component's name: `admin/users/list` (`AdminUsersListWidget`), not `admin/lists/user` (`AdminListsUserWidget`). Not for UI-kit components or shared hooks: they are generic and have no area. When a second page or widget joins an area, move the existing flat one into its folder with `Move or rename page` / `Move or rename widget` (`users` → `admin/users`).
|
|
76
|
-
|
|
77
|
-
## React widget type
|
|
78
|
-
|
|
79
|
-
Default **`with separated ui`**. Use `headless` only when consumers must supply different visuals for the same behavior, or the user asks. Use `monolithic` only on explicit request. "It's small" and "other widgets use another type" are not reasons. State any deviation in the plan.
|
|
58
|
+
| Clock | Always a port (`clock`, usually in Shared Kernel). A command or query never uses it: the use case reads the time and passes it in the input. |
|
|
80
59
|
|
|
81
60
|
## Where it goes
|
|
82
61
|
|
|
83
62
|
- Default: the context that owns the data and rules (`df-ps-plan-feature`, step 3).
|
|
84
|
-
- Shared
|
|
63
|
+
- Shared Kernel: technical, ownerless pieces (`clock`, `mailer` ports, shared HTTP client, errors like `unauthorized`) and **universal** entities / value objects: the same meaning and rules in every context, owned by none (`money`, `email`, `address`). A Shared Kernel domain service holds rules at the junction of these universal types only. Anything with one context's meaning or rules (`order-status`, `customer`) stays in that context, even if other contexts need it; they duplicate it in their own queries/commands.
|
|
85
64
|
- Another context's data or behavior → a query/command in the consuming context (step 9).
|
|
86
65
|
|
|
87
66
|
## Example
|
|
@@ -97,7 +76,7 @@ Default **`with separated ui`**. Use `headless` only when consumers must supply
|
|
|
97
76
|
| Discount ≤ 30% | 7 | `Order.applyDiscount()`: a rule about one aggregate's state; the use case passes the discount it got from the query |
|
|
98
77
|
| Place order, reorder | 8 | use cases `place-order`, `reorder` |
|
|
99
78
|
| Promo code check | 9 | query `promo-code-discount`: `prisma` if `marketing` shares the database, otherwise `http` to its endpoint |
|
|
100
|
-
| Email, order date | 10 | ports `mailer`, `clock` (Shared
|
|
79
|
+
| Email, order date | 10 | ports `mailer`, `clock` (Shared Kernel) |
|
|
101
80
|
| Free shipping for gold customers | 13 | domain service `shipping-policy`: takes `customer` and `order`, no I/O |
|
|
102
81
|
| Confirmation for both use cases | 14 | application service `order-confirmation` (gets `mailer`) |
|
|
103
82
|
| Invalid promo code | 1 | error `invalid-promo-code` in namespace `order` |
|
|
@@ -1,187 +1,14 @@
|
|
|
1
|
-
# df-scaffold generators:
|
|
1
|
+
# df-scaffold generators: common parts
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
What every generator shares: notation, the `Dependencies:` step, env-branched wiring and spec templates. Prompts and output of each generator are in `units/<unit>.md`.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Notation: `<C>` = `<rootFolder>/bounded-contexts/<context>` or `<rootFolder>/shared-kernel`. `n` = the entered kebab-case name, `N` = PascalCase, `v` = camelCase. `I` = implementation label (`prisma` → `Prisma`). Specs are generated without a prompt **only if `testingLibrary` is set**. `{pkg}` = output depends on that `@domain-first/*` package.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
{wire} Generators that create a wire (all below except endpoints, which ask their own two selects) then ask the checkbox `Dependencies:`, before `Overwrite them?`. It lists wired modules of `<C>` and of the Shared Layer (`(shared)` suffix), grouped under headers in this order: Repositories, Domain services, Ports, Application services, Queries, Commands, Use cases, Infrastructure services, Presentation services. Inside a group: by type name, `<C>` first. Headers are not counted: `toggle:<n,..>` numbers only modules, top to bottom. Answer `toggle:<n,..>` or `none`. It is skipped when nothing fits, so check `<C>/wiring/` and `<rootFolder>/shared/wiring/` before counting steps. What fits depends on the layer of the class the wire builds: domain → domain; application → domain, application; infrastructure (repository, command/query, and port implementations, infrastructure services) → domain, application ports (of `<C>` and the Shared Layer; no other application modules), infrastructure; presentation → application, presentation. On top of that, domain services see only domain services (no repositories), application services see only ports, commands and queries from application, use cases never see use cases, repository implementations never see repositories, command/query implementations see only infrastructure services. These are the defaults: `rules.dependencies` in the config changes them per kind (`use-cases`, `queries`, …), so count items from what the project's rules allow. Endpoints are never listed. Each chosen module goes into the wire (`wireClass(X, [wireUserRepository])`) and the constructor (`private readonly userRepository: UserRepository`, with `import type`), in the same order. An env-branched wire (repository, command/query, port) wires each implementation in isolation: instead of `Dependencies:` it asks `Dependencies for <Implementation>:` once per implementation, in the order of the wire (main, then test). Each list leaves out only what that implementation already has, and a list with nothing to choose is skipped. It may start with a `Suggested` group: infrastructure modules whose file name has the implementation label (its folder, e.g. `prisma`, `in-memory`) as whole words, such as `in-memory-db-infrastructure-service` for `in-memory`. They are listed there only, so numbering starts with them, and they are **checked**: `none` keeps them, `toggle:<n>` on one of them unchecks it.
|
|
10
|
-
|
|
11
|
-
## Bounded context
|
|
12
|
-
|
|
13
|
-
`"pick:Scaffold new bounded context" text:sales` → folder `<rootFolder>/bounded-contexts/sales/`; {errors} `domain/errors/index.ts` with `SalesErrors = errorNamespace('sales')`.
|
|
14
|
-
|
|
15
|
-
## Domain → New Aggregate (context only)
|
|
16
|
-
|
|
17
|
-
Prompts: name → `With Repository` → if yes: implementation (default = config persistence label) → `Add a test implementation` → if yes: test implementation (default `in-memory`).
|
|
18
|
-
|
|
19
|
-
`… pick:Domain "pick:New Aggregate" text:order yes default yes default`
|
|
20
|
-
|
|
21
|
-
- `<C>/domain/aggregates/n/`: `n.aggregate-root.ts` (`class N extends domainType()` {types}), `index.ts`, spec; with repository: `n-repository.ts` (`abstract class NRepository`), spec
|
|
22
|
-
- `<C>/infrastructure/repositories/I/I-n-repository.ts` per implementation (`class INRepository implements NRepository`)
|
|
23
|
-
- {wire} `<C>/wiring/repositories/wire-n-repository.ts` (env-branched)
|
|
24
|
-
- With `withInMemoryDb` in the config, the `in-memory` implementation can keep its section of the DB: `private readonly data: InMemoryDbInfrastructureService['ns']`, set in the constructor from its `inMemoryDbInfrastructureService` parameter; `ns = this.section<N>('NS');` is added to `<rootFolder>/shared/infrastructure/services/in-memory-db-infrastructure-service.ts` if missing (`N` needs an `id`). Without {wire} this always happens. {wire} `Dependencies for InMemoryNRepository:` lists the DB under `Suggested`, checked: kept, it gets the section and `wireInMemoryDbInfrastructureService` in its `wireClass`; unchecked, the implementation stays empty (`constructor() {}`) and no section is added.
|
|
25
|
-
|
|
26
|
-
## Domain → New Entity / New Value Object (context and Shared Layer)
|
|
27
|
-
|
|
28
|
-
Prompts: name → aggregate (select: existing aggregate folders | `No aggregate`; asked only if `<C>/domain/aggregates/` has aggregates, so never in Shared Layer).
|
|
29
|
-
|
|
30
|
-
`… pick:Domain "pick:New Entity" text:order-line pick:order`
|
|
31
|
-
`… pick:Domain "pick:New Value Object" text:money "pick:No aggregate"`
|
|
32
|
-
`"pick:Shared Layer" pick:Domain "pick:New Value Object" text:money`
|
|
33
|
-
|
|
34
|
-
- In an aggregate: `<C>/domain/aggregates/a/entities/n.entity.ts` or `<C>/domain/aggregates/a/value-objects/n.value-object.ts` (`class N extends domainType()` {types}), spec; `export * from './entities/n.entity'` (or `./value-objects/n.value-object`) appended to the aggregate's `index.ts`
|
|
35
|
-
- `No aggregate`: `<C>/domain/entities/n.entity.ts` or `<C>/domain/value-objects/n.value-object.ts`, spec; no barrel
|
|
36
|
-
|
|
37
|
-
## Domain → Errors (context and Shared Layer)
|
|
38
|
-
|
|
39
|
-
First prompt (select): `New error without namespace` | `New namespace` | `New error in namespace <ns>`, then a name.
|
|
40
|
-
|
|
41
|
-
`… pick:Domain pick:Errors "pick:New namespace" text:order`
|
|
42
|
-
`… pick:Domain pick:Errors "pick:New error in namespace order" text:not-found`
|
|
43
|
-
`… pick:Domain pick:Errors "pick:New error without" text:order-closed`
|
|
44
|
-
|
|
45
|
-
- Without namespace: appends `export class N extends CtxErrors.define('n') {}` to `<C>/domain/errors/index.ts`
|
|
46
|
-
- New namespace: `<C>/domain/errors/ns.ts` (`NsErrors = errorNamespace('ctx').subnamespace('ns')`) + `export * from './ns'` in `index.ts`
|
|
47
|
-
- In namespace: appends `export class NsN extends NsErrors.define('n') {}` to `ns.ts` (namespace first), extending the namespace the file exports
|
|
48
|
-
- Shared Layer: errors end with `SharedError`, namespaces with `SharedErrors`: `NSharedError`, `NsSharedErrors`, `NsNSharedError`
|
|
49
|
-
|
|
50
|
-
Re-running is safe: an existing namespace file is kept, and a line already in the file isn't added again.
|
|
51
|
-
|
|
52
|
-
`Ctx` = PascalCase of the context folder (`Shared` in Shared Layer). Requires `index.ts` with `CtxErrors` {errors}.
|
|
53
|
-
|
|
54
|
-
## Services: Domain / Application / Infrastructure / Presentation (context and Shared Layer)
|
|
55
|
-
|
|
56
|
-
Prompts: name. `L` = `domain` | `application` | `infrastructure` | `presentation`.
|
|
57
|
-
|
|
58
|
-
`… pick:Application "pick:New Service" text:checkout`
|
|
59
|
-
|
|
60
|
-
- `<C>/L/services/n-L-service.ts` (`class NLService`, e.g. `CheckoutApplicationService`), spec
|
|
61
|
-
- {wire} `<C>/wiring/L-services/wire-n-L-service.ts` (`wireClass(X, [])`)
|
|
62
|
-
|
|
63
|
-
## Application → New Use Case (context only)
|
|
64
|
-
|
|
65
|
-
Prompts: name. `… pick:Application "pick:New Use Case" text:place-order`
|
|
66
|
-
|
|
67
|
-
- `<C>/application/use-cases/n-use-case.ts`: {handlers} schemas + `handle = defineHandler(...)`, else an empty class; spec
|
|
68
|
-
- {wire} `<C>/wiring/use-cases/wire-n-use-case.ts`
|
|
69
|
-
|
|
70
|
-
## Application → New Command / New Query (context only)
|
|
71
|
-
|
|
72
|
-
Prompts: name → implementation (default = config persistence label) → `Add a test implementation` → if yes: test implementation (default `in-memory`).
|
|
73
|
-
|
|
74
|
-
`… pick:Application "pick:New Command" text:place-order default yes default`
|
|
75
|
-
`… pick:Application "pick:New Query" text:order-summary default no`
|
|
76
|
-
|
|
77
|
-
- `<C>/application/commands/n-command.ts`: abstract `NCommand` ({handlers} schemas + abstract `handle: Handler<…>`), spec
|
|
78
|
-
- `<C>/infrastructure/commands/I/I-n-command.ts` per implementation (`extends NCommand`, implements `handle`)
|
|
79
|
-
- {wire} `<C>/wiring/commands/wire-n-command.ts` (env-branched)
|
|
80
|
-
- With `withInMemoryDb` in the config, the `in-memory` implementation can get the whole DB: `constructor(private readonly inMemoryDbInfrastructureService: InMemoryDbInfrastructureService)`. No section is added. Without {wire} this always happens; {wire} it is the checked `Suggested` choice of `Dependencies for InMemoryN<Suffix>:`, and unchecking it leaves the implementation empty.
|
|
81
|
-
|
|
82
|
-
Queries: the same with `query` / `queries`.
|
|
83
|
-
|
|
84
|
-
## Application → New Port (context and Shared Layer)
|
|
85
|
-
|
|
86
|
-
Prompts: name → adapter implementation (default `api`) → `With test implementation` → if yes: test implementation (default `mock`).
|
|
87
|
-
|
|
88
|
-
`… pick:Application "pick:New Port" text:payment-gateway default yes default`
|
|
89
|
-
|
|
90
|
-
- `<C>/application/ports/n.ts` (abstract `N`; name it after the capability), spec
|
|
91
|
-
- `<C>/infrastructure/application-adapters/I/I-n.ts` per implementation (`class IN extends N`)
|
|
92
|
-
- {wire} `<C>/wiring/application-ports/wire-n.ts` (env-branched)
|
|
93
|
-
|
|
94
|
-
## Wire dependency (context and Shared Layer, needs wire)
|
|
7
|
+
Every step list starts with `"pick:Bounded Context: <ctx>"` or `"pick:Shared Kernel"`, then the layer, then the operation (abbreviated below as `…`).
|
|
95
8
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
`"pick:Bounded Context: users" "pick:Wire dependency" "pick:UserRepository (prisma)" toggle:1`
|
|
99
|
-
|
|
100
|
-
Edits the wire and the implementation classes in place; this never triggers `Overwrite them?`.
|
|
101
|
-
|
|
102
|
-
## Presentation → New Handlers-REST Endpoint (context only, needs handlers-rest)
|
|
103
|
-
|
|
104
|
-
Prompts: controller (select: existing | `New controller` → name) → method (`get` `post` `patch` `delete` `put`) → relative path (may be empty: `default`) → {wire} `Handler:` (select: queries, commands, and use cases of `<C>`, grouped; skipped if there are none).
|
|
105
|
-
|
|
106
|
-
`… pick:Presentation "pick:New Handlers" "pick:New controller" text:orders pick:get text:recent pick:RecentOrdersQuery`
|
|
107
|
-
`… pick:Presentation "pick:New Handlers" pick:orders pick:post default pick:PlaceOrder`
|
|
108
|
-
|
|
109
|
-
For `sales`, `orders`, `get`, `recent`:
|
|
110
|
-
|
|
111
|
-
- `<C>/presentation/rest/orders/recent/GET.ts`: `class OrdersRecentGetEndpoint(endpointGenerator, handler)`, route `['sales','orders','recent']`. `endpointGenerator: RestEndpointGeneratorPresentationService` (the Shared Layer generator from initialization) and `handler: RecentOrdersQuery` (`never` without a pick), both `import type`. `get handle()` calls `this.endpointGenerator(...)`, which doesn't compile until a generating getter is picked (`this.endpointGenerator.withoutGuards(...)`); that's expected, not a generator bug. Projects without the generator file get `EndpointGenerator` from handlers-rest.
|
|
112
|
-
- {wire} `<C>/wiring/presentation/rest/orders/wire-orders-recent-get-endpoint.ts` (`[wireRestEndpointGeneratorPresentationService, wireRecentOrdersQuery]`; `[]` without the generator file) + a line in that folder's `index.ts`
|
|
113
|
-
- {wire}, new controller only: `<C>/wiring/presentation/rest/index.ts`, `<rootFolder>/presentation/rest/wires.ts` (lines appended), `<rootFolder>/presentation/rest/index.ts` (`restHandlers`, created once)
|
|
114
|
-
|
|
115
|
-
The same controller, path, and method replace the existing endpoint (after `Overwrite them?`).
|
|
116
|
-
|
|
117
|
-
## React (needs useReact)
|
|
118
|
-
|
|
119
|
-
`"pick:Scaffold React module" "pick:New page" text:checkout` → `<rootFolder>/presentation/react/pages/n-page.tsx`
|
|
120
|
-
|
|
121
|
-
`"pick:Scaffold React module" "pick:New widget" text:cart "pick:with separated ui"` → `…/widgets/n/`:
|
|
122
|
-
|
|
123
|
-
- `with separated ui` (default): `n-widget.tsx`, `types.ts`, `ui/n-widget-ui.tsx`, `hooks/use-n-ui-model.ts`; with `storybookFramework`: `ui/n-widget-ui.stories.tsx` (CSF3: `meta` with `title: 'Widgets/N'`, `component: NWidgetUI`, story `Default`)
|
|
124
|
-
- `headless`: `n-widget.tsx`, `types.ts` (props include `UI`), `hooks/use-n-ui-model.ts`
|
|
125
|
-
- `monolithic`: `n-widget.tsx`
|
|
126
|
-
- every type: `index.ts` (`export * from './n-widget'`)
|
|
127
|
-
|
|
128
|
-
Page and widget names may have folders before them: `text:admin/panel/users` → `…/pages/admin/panel/admin-panel-users-page.tsx` and `…/widgets/admin/panel/users/`. The widget folder uses only the last segment; file names use the whole path (`admin-panel-users-page.tsx`, `admin-panel-users-widget.tsx`, `ui/admin-panel-users-widget-ui.tsx`, `hooks/use-admin-panel-users-ui-model.ts`), and so do code names (`AdminPanelUsersPage`, `AdminPanelUsersWidget`, `useAdminPanelUsersUIModel`); the story title follows the folders (`Widgets/Admin/Panel/Users`). `.` and `..` are rejected.
|
|
129
|
-
|
|
130
|
-
Move or rename a page or a widget only with df-scaffold, never by hand: `"pick:Scaffold React module" "pick:Move or rename widget" "pick:admin/users" text:team/users "yes"` (`Move or rename page` for pages; the list shows nested names, the default new name is the current one). It moves the widget folder (or the page with its `<name>-page.*` files), renames files and `<Name>Widget…` / `use<Name>UIModel` / `<Name>Page…` to the new name, updates a generated story title and every import of the module (relative and `tsconfig` aliases; importers of barrels re-exporting it get the renamed classes), and fixes relative imports inside it. Before `Apply?` it prints the files to move and to update; check them. An existing target or a move into itself is rejected.
|
|
131
|
-
|
|
132
|
-
`"pick:Scaffold React module" "pick:New UI-kit" text:date-picker` → `…/ui-kit/n/`:
|
|
133
|
-
|
|
134
|
-
- `n.tsx` (`type NProps`, `const N: FC<NProps>`)
|
|
135
|
-
- `index.ts` (`export * from './n'`)
|
|
136
|
-
- with `storybookFramework`: `n.stories.tsx` (CSF3: `meta` with `title: 'UI-kit/N'`, story `Default`)
|
|
137
|
-
|
|
138
|
-
No Storybook prompt: UI-kit and widget UI stories follow the config.
|
|
139
|
-
|
|
140
|
-
`"pick:Scaffold React module" "pick:New shared hook" text:debounce` → `…/presentation/react/hooks/use-n.ts` (`const useN = () => …`). A leading `use-` in the name is dropped, so `use-debounce` gives the same file.
|
|
141
|
-
|
|
142
|
-
### Story templates
|
|
143
|
-
|
|
144
|
-
Only for recreating a **missing** story (rule 2, exception 4).
|
|
145
|
-
|
|
146
|
-
UI-kit, at `…/ui-kit/n/n.stories.tsx`:
|
|
147
|
-
|
|
148
|
-
```tsx
|
|
149
|
-
import type { Meta, StoryObj } from "<storybookFramework>";
|
|
150
|
-
import { N } from "./n";
|
|
151
|
-
|
|
152
|
-
const meta = {
|
|
153
|
-
title: "UI-kit/N",
|
|
154
|
-
component: N,
|
|
155
|
-
} satisfies Meta<typeof N>;
|
|
156
|
-
|
|
157
|
-
export default meta;
|
|
158
|
-
|
|
159
|
-
type Story = StoryObj<typeof meta>;
|
|
160
|
-
|
|
161
|
-
export const Default: Story = {
|
|
162
|
-
args: {},
|
|
163
|
-
};
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
Widget UI (`with separated ui` only), at `…/widgets/n/ui/n-widget-ui.stories.tsx`:
|
|
167
|
-
|
|
168
|
-
```tsx
|
|
169
|
-
import type { Meta, StoryObj } from "<storybookFramework>";
|
|
170
|
-
import { NWidgetUI } from "./n-widget-ui";
|
|
171
|
-
|
|
172
|
-
const meta = {
|
|
173
|
-
title: "Widgets/N",
|
|
174
|
-
component: NWidgetUI,
|
|
175
|
-
} satisfies Meta<typeof NWidgetUI>;
|
|
176
|
-
|
|
177
|
-
export default meta;
|
|
178
|
-
|
|
179
|
-
type Story = StoryObj<typeof meta>;
|
|
9
|
+
Any generator: if the run would replace existing files, the last prompt is the confirm `Overwrite them?` (the files are listed above it). Without it, nothing extra is asked. Added lines (barrels, errors, wiring indexes) never trigger it.
|
|
180
10
|
|
|
181
|
-
|
|
182
|
-
args: {},
|
|
183
|
-
};
|
|
184
|
-
```
|
|
11
|
+
{wire} Generators that create a wire (all except endpoints, which ask their own two selects) then ask the checkbox `Dependencies:`, before `Overwrite them?`. It lists wired modules of `<C>` and of the Shared Kernel (`(shared-kernel)` suffix), grouped under headers in this order: Repositories, Domain services, Ports, Application services, Queries, Commands, Use cases, Infrastructure services, Presentation services. Inside a group: by type name, `<C>` first. Headers are not counted: `toggle:<n,..>` numbers only modules, top to bottom. Answer `toggle:<n,..>` or `none`. It is skipped when nothing fits, so check `<C>/wiring/` and `<rootFolder>/shared-kernel/wiring/` before counting steps. What fits depends on the layer of the class the wire builds: domain → domain; application → domain, application; infrastructure (repository, command/query, and port implementations, infrastructure services) → domain, application ports (of `<C>` and the Shared Kernel; no other application modules), infrastructure; presentation → application, presentation. On top of that, domain services see only domain services (no repositories), application services see only ports, commands and queries from application, use cases never see use cases, repository implementations never see repositories, command/query implementations see only infrastructure services. These are the defaults: `rules.dependencies` in the config changes them per kind (`use-cases`, `queries`, …), so count items from what the project's rules allow. Endpoints are never listed. Each chosen module goes into the wire (`wireClass(X, [wireUserRepository])`) and the constructor (`private readonly userRepository: UserRepository`, with `import type`), in the same order. An env-branched wire (repository, command/query, port) wires each implementation in isolation: instead of `Dependencies:` it asks `Dependencies for <Implementation>:` once per implementation, in the order of the wire (main, then test). Each list leaves out only what that implementation already has, and a list with nothing to choose is skipped. It may start with a `Suggested` group: infrastructure modules whose file name has the implementation label (its folder, e.g. `prisma`, `in-memory`) as whole words, such as `in-memory-db-infrastructure-service` for `in-memory`. They are listed there only, so numbering starts with them, and they are **checked**: `none` keeps them, `toggle:<n>` on one of them unchecks it.
|
|
185
12
|
|
|
186
13
|
## Env-branched wiring {wire}
|
|
187
14
|
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Aggregate and repository
|
|
2
|
+
|
|
3
|
+
When: a thing with identity, lifecycle, and rules about its own state, owned by this context and stored on its own (`../choosing-components.md`, step 4). A rule about its own state is a method on it (step 7), not a new unit. Loading/saving one aggregate is a repository method, not a query or command.
|
|
4
|
+
|
|
5
|
+
## Generate (context only)
|
|
6
|
+
|
|
7
|
+
Prompts: name → `With Repository` → if yes: implementation (default = config persistence label) → `Add a test implementation` → if yes: test implementation (default `in-memory`) → {wire} `Dependencies for <Implementation>:` per implementation (`../generators.md`).
|
|
8
|
+
|
|
9
|
+
`… pick:Domain "pick:New Aggregate" text:order yes default yes default`
|
|
10
|
+
|
|
11
|
+
- `<C>/domain/aggregates/n/`: `n.aggregate-root.ts` (`class N extends domainType()` {types}), `index.ts`, spec; with repository: `n-repository.ts` (`abstract class NRepository`), spec
|
|
12
|
+
- `<C>/infrastructure/repositories/I/I-n-repository.ts` per implementation (`class INRepository implements NRepository`)
|
|
13
|
+
- {wire} `<C>/wiring/repositories/wire-n-repository.ts` (env-branched)
|
|
14
|
+
- With `withInMemoryDb` in the config, the `in-memory` implementation can keep its section of the DB: `private readonly data: InMemoryDbInfrastructureService['ns']`, set in the constructor from its `inMemoryDbInfrastructureService` parameter; `ns = this.section<N>('NS');` is added to `<rootFolder>/shared-kernel/infrastructure/services/in-memory-db-infrastructure-service.ts` if missing (`N` needs an `id`). Without {wire} this always happens. {wire} `Dependencies for InMemoryNRepository:` lists the DB under `Suggested`, checked: kept, it gets the section and `wireInMemoryDbInfrastructureService` in its `wireClass`; unchecked, the implementation stays empty (`constructor() {}`) and no section is added.
|
|
15
|
+
|
|
16
|
+
Its entities and value objects come after it: [entity-value-object](entity-value-object.md), picking this aggregate.
|
|
17
|
+
|
|
18
|
+
## Implement
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
export class Order extends domainType(
|
|
22
|
+
z.object({
|
|
23
|
+
id: z.instanceof(OrderId),
|
|
24
|
+
lines: z.array(z.instanceof(OrderLine)),
|
|
25
|
+
status: z.enum(["open", "paid"]),
|
|
26
|
+
}),
|
|
27
|
+
) {
|
|
28
|
+
withPayment = () => {
|
|
29
|
+
if (this.status === "paid") {
|
|
30
|
+
throw new AlreadyPaidOrderSalesError({
|
|
31
|
+
id: this.id.snapshot,
|
|
32
|
+
});
|
|
33
|
+
}
|
|
34
|
+
return this.with({ status: "paid" });
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
- Use the schema library the project already uses. Methods return new instances. Invalid input throws `TypeParsingError`.
|
|
40
|
+
- The aggregate is rich and knows nothing about storage: its rules and factories are methods; no repository calls, persistence fields, or storage mapping.
|
|
41
|
+
- Repository contract: abstract members (`abstract findById(id: OrderId): Promise<Order | null>`, `abstract save(order: Order): Promise<void>`). A rule about a set of aggregates (uniqueness, "at most N per day") is a repository method that queries it, checked in the use case.
|
|
42
|
+
- Implementations map storage ⇄ aggregates. The in-memory one behaves like the real one for what tests use; with the in-memory DB, it keeps the aggregates in its section (`this.data.save(order)`, `this.data.withId(id)`).
|
|
43
|
+
- Refer to other contexts' entities by id only.
|
|
44
|
+
|
|
45
|
+
## Test
|
|
46
|
+
|
|
47
|
+
Extend the generated specs in the same files: aggregate rules on the root, the repository contract against the test implementation.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Bounded context
|
|
2
|
+
|
|
3
|
+
When: a concept with its own lifecycle and vocabulary, or a different business owner (`df-ps-plan-feature`, step 3). Never one context per feature.
|
|
4
|
+
|
|
5
|
+
## Generate
|
|
6
|
+
|
|
7
|
+
`"pick:Scaffold new bounded context" text:sales` → empty folder `<rootFolder>/bounded-contexts/sales/`. No error namespace until the first error ([errors](errors.md)).
|
|
8
|
+
|
|
9
|
+
Name: a business area in kebab-case (`sales`, `reviews`), not a feature.
|
|
10
|
+
|
|
11
|
+
## Implement
|
|
12
|
+
|
|
13
|
+
Nothing to fill in. Everything inside comes from the other units. The context imports nothing from other contexts and they import nothing from it (`df-ps-implement`, "Bounded context isolation").
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Command and query
|
|
2
|
+
|
|
3
|
+
When (`../choosing-components.md`, steps 9 and 11): data or behavior of **another context**, or one atomic read/write on this context's own storage that isn't "load/save one aggregate" (read model, report, bulk update). A query reads, a command writes.
|
|
4
|
+
|
|
5
|
+
- **One atomic operation of one kind of implementation**: one database operation (several statements in one transaction count as one), one request to another context's endpoint, one message sent to another context (an external API is never a query or command: it's a port). Several operations, a mix of storages, or logic between the steps → several queries/commands, composed in a use case.
|
|
6
|
+
- A query only reads: it never changes any state, not even idempotently (no cache filling, no default settings created if missing), and never calls a command. A command returns nothing or only the minimum needed to use its result later (the created order's ID), never the changed data: read that with a query.
|
|
7
|
+
- Another context: input/output are this context's own models, duplicated in its terms. The implementation reaches it the simplest available way: a shared database → directly (the persistence label, e.g. `prisma`); otherwise the way chosen in the plan (`df-ps-plan-feature`, step 3, rule 4), by default its REST endpoint (`http`). No imports from the other context.
|
|
8
|
+
|
|
9
|
+
## Generate (context only)
|
|
10
|
+
|
|
11
|
+
Prompts: name → implementation (default = config persistence label) → `Add a test implementation` → if yes: test implementation (default `in-memory`) → {wire} `Dependencies for <Implementation>:` per implementation (`../generators.md`).
|
|
12
|
+
|
|
13
|
+
`… pick:Application "pick:New Command" text:place-order default yes default`
|
|
14
|
+
`… pick:Application "pick:New Query" text:order-summary default no`
|
|
15
|
+
|
|
16
|
+
- `<C>/application/commands/n-command.ts`: abstract `NCommand` ({handlers} schemas + abstract `handle: Handler<…>`), spec
|
|
17
|
+
- `<C>/infrastructure/commands/I/I-n-command.ts` per implementation (`extends NCommand`, implements `handle`)
|
|
18
|
+
- {wire} `<C>/wiring/commands/wire-n-command.ts` (env-branched)
|
|
19
|
+
- With `withInMemoryDb` in the config, the `in-memory` implementation can get the whole DB: `constructor(private readonly inMemoryDbInfrastructureService: InMemoryDbInfrastructureService)`. No section is added. Without {wire} this always happens; {wire} it is the checked `Suggested` choice of `Dependencies for InMemoryN<Suffix>:`, and unchecking it leaves the implementation empty.
|
|
20
|
+
|
|
21
|
+
Queries: the same with `query` / `queries`.
|
|
22
|
+
|
|
23
|
+
## Implement
|
|
24
|
+
|
|
25
|
+
- {handlers} The abstract contract holds the static schemas and `abstract handle`; replace the `{}` schemas with real ones. Each infrastructure implementation defines `handle` with the contract's schemas and writes only its `handler` callback.
|
|
26
|
+
- An implementation performs its one operation: no business logic, no steps around it. Its only wired dependencies are infrastructure services (the client it runs on); repositories, ports, domain services and other commands and queries stay with the use case. Needing more → it's several commands/queries.
|
|
27
|
+
- It uses domain models in its input/output; the time comes in the input, never from the `clock` port.
|
|
28
|
+
- The test implementation returns fixed data (another context) or works on the in-memory DB (own storage), so tests never run another context.
|
|
29
|
+
|
|
30
|
+
## Test
|
|
31
|
+
|
|
32
|
+
Extend the generated spec: the handler against the test implementation via `handle(...)`.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# REST endpoint {handlers-rest}
|
|
2
|
+
|
|
3
|
+
When: an HTTP entry point (`../choosing-components.md`, step 2). It exposes a query, a command or a use case of its context.
|
|
4
|
+
|
|
5
|
+
## Generate (context only)
|
|
6
|
+
|
|
7
|
+
Prompts: controller (select: existing | `New controller` → name) → method (`get` `post` `patch` `delete` `put`) → relative path (may be empty: `default`) → {wire} `Handler:` (select: queries, commands, and use cases of `<C>`, grouped; skipped if there are none).
|
|
8
|
+
|
|
9
|
+
`… pick:Presentation "pick:New Handlers" "pick:New controller" text:orders pick:get text:recent pick:RecentOrdersQuery`
|
|
10
|
+
`… pick:Presentation "pick:New Handlers" pick:orders pick:post default pick:PlaceOrder`
|
|
11
|
+
|
|
12
|
+
For `sales`, `orders`, `get`, `recent`:
|
|
13
|
+
|
|
14
|
+
- `<C>/presentation/rest/orders/recent/GET.ts`: `class OrdersRecentGetEndpoint(endpointGenerator, handler)`, route `['sales','orders','recent']`. `endpointGenerator: RestEndpointGeneratorPresentationService` (the Shared Kernel generator) and `handler: RecentOrdersQuery` (`never` without a pick), both `import type`. `get handle()` calls `this.endpointGenerator(...)`, which doesn't compile until a generating getter is picked (`this.endpointGenerator.withoutGuards(...)`); that's expected, not a generator bug. Projects without the generator file get `EndpointGenerator` from handlers-rest.
|
|
15
|
+
- {wire} `<C>/wiring/presentation/rest/orders/wire-orders-recent-get-endpoint.ts` (`[wireRestEndpointGeneratorPresentationService, wireRecentOrdersQuery]`; `[]` without the generator file) + a line in that folder's `index.ts`
|
|
16
|
+
- {wire}, new controller only: `<C>/wiring/presentation/rest/index.ts`, `<rootFolder>/presentation/rest/wires.ts` (lines appended), `<rootFolder>/presentation/rest/index.ts` (`restHandlers`, created once)
|
|
17
|
+
|
|
18
|
+
The same controller, path, and method replace the existing endpoint (after `Overwrite them?`). Generate the exposed handler first, so `Handler:` lists it. If `handler: never` is left, re-run the endpoint generator once the handler exists, as an approved overwrite; don't replace it by hand.
|
|
19
|
+
|
|
20
|
+
## Implement
|
|
21
|
+
|
|
22
|
+
1. Generator: `df-init` (or the `REST endpoint generator` integration) creates `RestEndpointGeneratorPresentationService` in `<rootFolder>/shared-kernel/presentation/services/`; every endpoint uses it. Set the module-level `const adapter` above the class (`undefined` until set) to the HTTP framework's adapter; the class reads it through closure. If the Next adapter was connected, the file already imports `nextAdapter` from `@domain-first/handlers-next` and passes it instead; just make sure that package is installed.
|
|
23
|
+
2. Errors: invalid requests (`400`) are answered by `invalidRequest()` of `@domain-first/handlers-rest` in `errors`; don't map `RequestParsingError` / `InputMappingError` by hand, add your own mappings next to it: `errors: [httpError(MyError, 404), invalidRequest()]`. Map domain errors with `httpError(ErrorClass, status, { description, message, details: { schema, map } })` (one class) or `httpStatus(status, { code, match })` (many errors, one code); the first match wins, so put specific mappings first, importing them from the contexts' `domain/errors` (the only thing `shared-kernel/` may import from a context, besides domain models in the in-memory DB).
|
|
24
|
+
3. A new kind of endpoint (auth, other context) is a new getter returning `createEndpoint({ context, errors: [..., invalidRequest()] })(adapter) as EndpointGenerator` (`nextAdapter` with the Next adapter), next to `withoutGuards`.
|
|
25
|
+
4. Complete `get handle()`: pick the generating getter that fits the endpoint (`this.endpointGenerator.withoutGuards(...)`, or one with the needed guards), then `.input(...)`, `.mapInput(...)`, optional `.output(...)`, `.mapOutput(...)`.
|
|
26
|
+
5. Register `restHandlers` from `<rootFolder>/presentation/rest/index.ts` in the server bootstrap (`df-ps-scaffold` `SKILL.md`, rule 2, exception 5). With the Next adapter and wire, `app/api/[...path]/route.ts` (or `src/app/…`) already serves them through `nextEndpoints(restHandlers)`; it compiles once the first endpoint exists.
|
|
27
|
+
|
|
28
|
+
After new endpoints, regenerate the OpenAPI document and the API client with the project's scripts (tool runs in the plan).
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Entity and value object
|
|
2
|
+
|
|
3
|
+
When (`../choosing-components.md`, steps 5–6): used only inside one aggregate → in that aggregate; used by several aggregates or a domain service → `No aggregate`; universal, with the same meaning in every context (`money`, `email`, `address`) → Shared Kernel.
|
|
4
|
+
|
|
5
|
+
## Generate (context and Shared Kernel)
|
|
6
|
+
|
|
7
|
+
Prompts: name → aggregate (select: existing aggregate folders | `No aggregate`; asked only if `<C>/domain/aggregates/` has aggregates, so never in Shared Kernel).
|
|
8
|
+
|
|
9
|
+
`… pick:Domain "pick:New Entity" text:order-line pick:order`
|
|
10
|
+
`… pick:Domain "pick:New Value Object" text:money "pick:No aggregate"`
|
|
11
|
+
`"pick:Shared Kernel" pick:Domain "pick:New Value Object" text:money`
|
|
12
|
+
|
|
13
|
+
- In an aggregate: `<C>/domain/aggregates/a/entities/n.entity.ts` or `<C>/domain/aggregates/a/value-objects/n.value-object.ts` (`class N extends domainType()` {types}), spec; `export * from './entities/n.entity'` (or `./value-objects/n.value-object`) appended to the aggregate's `index.ts`
|
|
14
|
+
- `No aggregate`: `<C>/domain/entities/n.entity.ts` or `<C>/domain/value-objects/n.value-object.ts`, spec; no barrel
|
|
15
|
+
|
|
16
|
+
Generate the aggregate first ([aggregate](aggregate.md)).
|
|
17
|
+
|
|
18
|
+
## Implement
|
|
19
|
+
|
|
20
|
+
- `domainType(...)` classes like the aggregate root: use the schema library the project already uses; methods return new instances; invalid input throws `TypeParsingError`.
|
|
21
|
+
- Rich, with no knowledge of storage: their rules and factories are their methods, using the standard library where it suffices. No repository calls, persistence fields, or storage mapping.
|
|
22
|
+
- A rule about one entity / value object → its method. The junction of several → a [domain service](services.md), unless they all belong to one aggregate → a method on that aggregate.
|
|
23
|
+
- Inside an aggregate they are exported from its `index.ts`; import them from there.
|
|
24
|
+
|
|
25
|
+
## Test
|
|
26
|
+
|
|
27
|
+
Extend the generated `<name>.entity.spec.ts` / `<name>.value-object.spec.ts` with their rules (e.g. rating is 1–5).
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Errors {errors}
|
|
2
|
+
|
|
3
|
+
When: a business failure callers must recognize (`../choosing-components.md`, step 1). Technical, ownerless ones (`unauthorized`) go to the Shared Kernel.
|
|
4
|
+
|
|
5
|
+
## Generate (context and Shared Kernel)
|
|
6
|
+
|
|
7
|
+
First prompt (select): `New error without namespace` | `New namespace` | `New error in namespace <ns>`, then a name.
|
|
8
|
+
|
|
9
|
+
`… pick:Domain pick:Errors "pick:New namespace" text:order`
|
|
10
|
+
`… pick:Domain pick:Errors "pick:New error in namespace order" text:not-found`
|
|
11
|
+
`… pick:Domain pick:Errors "pick:New error without" text:order-closed`
|
|
12
|
+
|
|
13
|
+
- Without namespace: appends `export class N extends CtxErrors.define('n') {}` to `<C>/domain/errors/index.ts`; the first one also puts `CtxErrors = errorNamespace('ctx')` (with its import) at the top of `index.ts`
|
|
14
|
+
- New namespace: `<C>/domain/errors/ns.ts` (`NsErrors = errorNamespace('ctx').subnamespace('ns')`) + `export * from './ns'` in `index.ts`
|
|
15
|
+
- In namespace: appends `export class NsN extends NsErrors.define('n') {}` to `ns.ts` (namespace first), extending the namespace the file exports
|
|
16
|
+
- Shared Kernel: errors end with `SharedKernelError`, namespaces with `SharedKernelErrors`: `NSharedKernelError`, `NsSharedKernelErrors`, `NsNSharedKernelError`
|
|
17
|
+
|
|
18
|
+
`Ctx` = PascalCase of the context folder (`SharedKernel` in Shared Kernel). Contexts start without errors: `index.ts` appears with the first error or namespace. Re-running is safe: an existing namespace file is kept, and a line already in the file isn't added again.
|
|
19
|
+
|
|
20
|
+
A namespace groups the errors of one area (`order`, `payment`); `New error in namespace` is listed only once the namespace exists, so plan `New namespace` first.
|
|
21
|
+
|
|
22
|
+
## Implement
|
|
23
|
+
|
|
24
|
+
- Details: `.define<{ orderId: string }>('not-found')`.
|
|
25
|
+
- Throw `new XError({...})`; recognize with `XError.is(e)`, or `XError.matchesCode(data)` after serialization.
|
|
26
|
+
- Import a context's errors from its `domain/errors`. Only `shared-kernel/` may import another context's errors, e.g. to map them to HTTP statuses in the endpoint generator ([endpoint](endpoint.md)).
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Port
|
|
2
|
+
|
|
3
|
+
When: something that leaves this context's code and storage: an external system or time (`../choosing-components.md`, step 10, "Port or service?"). Own storage → repository, command or query; another context → a query or command, never a port. One method is enough: a single read from an external system is still a port. Another context is only a folder in `bounded-contexts/`; any other service (another team's API, a SaaS) is external. Wanting to mock a class or imagining multiple implementations is not enough. The `clock` port is always a port, usually in the Shared Kernel.
|
|
4
|
+
|
|
5
|
+
## Generate (context and Shared Kernel)
|
|
6
|
+
|
|
7
|
+
Prompts: name → adapter implementation (default `api`) → `With test implementation` → if yes: test implementation (default `mock`) → {wire} `Dependencies for <Implementation>:` per implementation (`../generators.md`).
|
|
8
|
+
|
|
9
|
+
`… pick:Application "pick:New Port" text:payment-gateway default yes default`
|
|
10
|
+
|
|
11
|
+
- `<C>/application/ports/n.ts` (abstract `N`; name it after the capability), spec
|
|
12
|
+
- `<C>/infrastructure/application-adapters/I/I-n.ts` per implementation (`class IN extends N`)
|
|
13
|
+
- {wire} `<C>/wiring/application-ports/wire-n.ts` (env-branched)
|
|
14
|
+
|
|
15
|
+
## Implement
|
|
16
|
+
|
|
17
|
+
- Abstract members in the port, described in the capability's terms (`charge(amount: Money)`), not the provider's.
|
|
18
|
+
- One implementation per adapter: `api` performs the real interaction (an SDK or HTTP client, through an [infrastructure service](services.md) for the client); `mock`/`fake` is deterministic.
|
|
19
|
+
- Use the Shared Kernel `clock` port instead of `new Date()` / `Date.now()` in domain and application code.
|
|
20
|
+
|
|
21
|
+
## Test
|
|
22
|
+
|
|
23
|
+
`NODE_ENV=test` wires the test implementation, so the logic that uses the port is tested with it.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Services: domain, application, infrastructure, presentation
|
|
2
|
+
|
|
3
|
+
When (`../choosing-components.md`, steps 12–15, "Port or service?"):
|
|
4
|
+
|
|
5
|
+
- **Domain service**: a rule at the junction of several entities / value objects not all belonging to one aggregate, no I/O. It takes the aggregates and values it needs as arguments; loading them is the caller's job. In the Shared Kernel only for junctions of universal types.
|
|
6
|
+
- **Application service**: application logic reused by 2+ use cases, with external interaction or storage access delegated to injected ports, commands or queries. A composition needed by one use case stays in it.
|
|
7
|
+
- **Infrastructure service**: a technical helper used only by infrastructure code; also the home of a value that isn't a wired module (a database or SDK client, a config value), named after the implementation label (`prisma`, `stripe`).
|
|
8
|
+
- **Presentation service**: a helper used only by presentation code.
|
|
9
|
+
|
|
10
|
+
## Generate (context and Shared Kernel)
|
|
11
|
+
|
|
12
|
+
Prompts: name → {wire} `Dependencies:` (`../generators.md`). `L` = `domain` | `application` | `infrastructure` | `presentation`.
|
|
13
|
+
|
|
14
|
+
`… pick:Application "pick:New Service" text:checkout`
|
|
15
|
+
|
|
16
|
+
- `<C>/L/services/n-L-service.ts` (`class NLService`, e.g. `CheckoutApplicationService`), spec
|
|
17
|
+
- {wire} `<C>/wiring/L-services/wire-n-L-service.ts` (`wireClass(X, [])`)
|
|
18
|
+
|
|
19
|
+
## Implement
|
|
20
|
+
|
|
21
|
+
- Domain services take and return domain types. Pure: no I/O, ports, or repositories, not even injected ones; they work with the data they are handed. They depend only on other domain services.
|
|
22
|
+
- Application services have no `handle`: a use case is how an endpoint reaches their logic. They call injected ports, commands and queries, never external SDKs, HTTP clients, or another context directly.
|
|
23
|
+
- Infrastructure services: an external client or config value is created or read by the service itself (`readonly client = new PrismaClient()`), with no constructor parameter for it. Implementations get the service through `df-scaffold`, where it shows up under `Suggested`. Wrap its wire in `memoWire(...)` when one instance must be shared (a connection pool, an in-memory store). No `wireValue(...)`.
|
|
24
|
+
- Infrastructure never sees application services. Logic infrastructure needs from one: pure logic without ports → a domain service; logic over ports → call the ports directly; technical (mapping, retries, external API formats) → an infrastructure service.
|
|
25
|
+
|
|
26
|
+
## Test
|
|
27
|
+
|
|
28
|
+
Test a service's logic with fake dependencies in its generated spec.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Use case
|
|
2
|
+
|
|
3
|
+
When: one business action a user or system triggers that doesn't fit into a single query or command (`../choosing-components.md`, step 8). **No proxy use cases**: an action that is exactly one query or command gets none, because every query and command is a handler an endpoint can use directly. A use case whose logic lives in an application service is not a proxy.
|
|
4
|
+
|
|
5
|
+
## Generate (context only)
|
|
6
|
+
|
|
7
|
+
Prompts: name → {wire} `Dependencies:` (`../generators.md`; use cases never see use cases by default).
|
|
8
|
+
|
|
9
|
+
`… pick:Application "pick:New Use Case" text:place-order`
|
|
10
|
+
|
|
11
|
+
- `<C>/application/use-cases/n-use-case.ts`: {handlers} schemas + `handle = defineHandler(...)`, else an empty class; spec
|
|
12
|
+
- {wire} `<C>/wiring/use-cases/wire-n-use-case.ts`
|
|
13
|
+
|
|
14
|
+
Generate its dependencies (repositories, ports, commands, queries, application services) first, so `Dependencies:` lists them.
|
|
15
|
+
|
|
16
|
+
## Implement
|
|
17
|
+
|
|
18
|
+
- {handlers} The member is `handle = defineHandler({ inputSchema, outputSchema, handler })`. Replace the static `{}` schemas with real ones and write the logic in the `handler` callback; dependencies come through the constructor.
|
|
19
|
+
- It composes repositories, ports, commands, queries and domain services: loads aggregates, calls their methods, saves them. Reading the time: the `clock` port, then pass the time into commands and queries in their input.
|
|
20
|
+
- A rule about a set of aggregates: a repository method that queries it, plus a check and a domain error here.
|
|
21
|
+
- Call others' handlers with `x.handle(input)` (returns a result) or `x.handle.unsafe(input)` (throws).
|
|
22
|
+
|
|
23
|
+
## Test
|
|
24
|
+
|
|
25
|
+
Extend the generated spec with handler tests via `handle(...)`, wired with test implementations (`NODE_ENV=test`).
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Wire dependency {wire}
|
|
2
|
+
|
|
3
|
+
When: an existing wired module needs a new dependency (`df-ps-scaffold` `SKILL.md`, rule 3). New modules get theirs in the generator's `Dependencies:` step instead.
|
|
4
|
+
|
|
5
|
+
## Generate (context and Shared Kernel)
|
|
6
|
+
|
|
7
|
+
Prompts: module (select: wired modules of `<C>`, grouped as in `Dependencies:`, endpoints excluded; an env-branched module is listed once per implementation, e.g. `UserRepository (prisma)`, `UserRepository (in-memory)`) → `Dependencies:`, or `Dependencies for <Implementation>:` for the chosen implementation only (`../generators.md`). Modules already in the wire are not listed. If nothing fits, it prints `No dependencies available for this module.` and changes nothing.
|
|
8
|
+
|
|
9
|
+
`"pick:Bounded Context: users" "pick:Wire dependency" "pick:UserRepository (prisma)" toggle:1`
|
|
10
|
+
|
|
11
|
+
Edits the wire and the implementation classes in place; this never triggers `Overwrite them?`. List it in the plan as a run for the existing module.
|
|
12
|
+
|
|
13
|
+
## Implement
|
|
14
|
+
|
|
15
|
+
Use the injected dependency in the class body. Don't edit the constructor parameters or the wire list by hand. A dependency the CLI doesn't offer is forbidden by the dependency rules or by context isolation: change the design instead (a port, a query or command, an infrastructure service).
|