@domain-first/project-structure 4.2.2 → 5.0.1
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 +3 -3
- package/dist/201.js +20 -35
- package/dist/config-file.d.ts +8 -16
- package/dist/dependency-rules.d.ts +14 -23
- package/dist/index.cjs +95 -259
- package/dist/index.js +85 -235
- package/dist/lint.cjs +22 -37
- package/dist/lint.js +2 -2
- package/dist/wiring.d.ts +1 -1
- package/package.json +1 -1
- package/skills/df-ps-implement/SKILL.md +24 -13
- package/skills/df-ps-plan-feature/SKILL.md +3 -3
- package/skills/df-ps-project-scripts/SKILL.md +1 -1
- package/skills/df-ps-scaffold/SKILL.md +2 -2
- package/skills/df-ps-scaffold/references/choosing-components.md +18 -20
- package/skills/df-ps-scaffold/references/generators.md +6 -11
|
@@ -13,7 +13,7 @@ Generated files contain placeholders: empty classes, `{}` schemas, `[]` dependen
|
|
|
13
13
|
- Keep generated names and paths: barrels, wiring, specs, and `presentation/rest/wires.ts` import them.
|
|
14
14
|
- Layers: domain imports nothing from other layers. Application uses domain and its own abstractions. Infrastructure implements repositories, contracts, and ports, and may use application ports (of its context and the Shared Layer), never other application modules. Infrastructure needing logic from an application service means the logic is misplaced: pure logic without ports → a domain service; logic over ports → call those ports directly; technical logic (mapping, retries, formatting for an external API) → an infrastructure service. Presentation calls application handlers. Only `wiring/` knows concrete classes.
|
|
15
15
|
- Constructors take abstractions (`OrderRepository`, abstract `PlaceOrderCommand`, port `PaymentGateway`), never `PrismaOrderRepository`.
|
|
16
|
-
- Implementation order: domain → application → schema tool runs (migrations, only if infrastructure needs data the database lacks) → infrastructure (repositories,
|
|
16
|
+
- Implementation order: domain → application → schema tool runs (migrations, only if infrastructure needs data the database lacks) → infrastructure (repositories, commands/queries, adapters) → endpoints → other tool runs (OpenAPI, API client) → React. Widgets need the regenerated client. How to run tools and handle their output: the project's scripts skill (`project-scripts`), if there is one.
|
|
17
17
|
- Run the project's tsc/lint/tests after each component.
|
|
18
18
|
- What each kind of module may use follows the defaults in these skills unless `rules.dependencies` in the config changes them; then follow the config, in imports as well as in wiring.
|
|
19
19
|
|
|
@@ -21,13 +21,13 @@ Generated files contain placeholders: empty classes, `{}` schemas, `[]` dependen
|
|
|
21
21
|
|
|
22
22
|
A file in context A imports **nothing** from context B: no types (`import type` too), barrels, aliases, errors, or wiring. No exceptions: every context must be movable to its own service.
|
|
23
23
|
|
|
24
|
-
- A needs B's data or behavior →
|
|
24
|
+
- A needs B's data or behavior → a **query** (read) or **command** (write) in A. Its input/output are A's own models, duplicated in A's terms; B's models never appear in A.
|
|
25
25
|
- Its infrastructure implementation reaches B's data **the simplest available way**: a shared database → query it directly (e.g. `prisma`); otherwise the way chosen in the plan (`df-ps-plan-feature`, step 3, rule 4), by default B's REST endpoint (`http`), like an external service. Either way it maps the result to A's models and errors and imports nothing from B. Its test implementation returns fixed data, so A's tests never run B.
|
|
26
26
|
- Refer to B's entities by id only.
|
|
27
27
|
- `shared/` may import any context's **`domain/errors`** (e.g. to map them to HTTP statuses), and nothing else from a context. The one exception: the shared in-memory DB, `shared/infrastructure/services/in-memory-db-infrastructure-service.ts`, may also import any context's **domain models** (aggregate roots, entities, value objects: the `domainType` classes under `domain/aggregates/`, `domain/entities/`, `domain/value-objects/`) to type its sections, never repository contracts or anything outside `domain/`. Don't move a context's domain concepts into `shared/` to share them between contexts; only universal entities / value objects (`money`, `email`) live there.
|
|
28
28
|
- `<rootFolder>/presentation/rest/` (the generated `wires.ts`, `index.ts`) may import every context's REST wiring.
|
|
29
29
|
- `<rootFolder>/presentation/react/` imports **nothing** from contexts whenever it can avoid it (`ui-kit/` never does). If the project has a generated API client (orval, openapi-typescript, … from the OpenAPI document built by `generateOpenAPI`), use its hooks and types only. As a fallback, without such a client, it may import **only endpoint contract types**: `import type` from `<C>/presentation/rest/**`, e.g. `type Contract = EndpointContract<OrdersRecentGetEndpoint['handle']>`. No value imports, no `import { type X }`, nothing from other layers.
|
|
30
|
-
- Need a forbidden import? A's own
|
|
30
|
+
- Need a forbidden import? A's own query or command is missing. Plan it and generate it.
|
|
31
31
|
|
|
32
32
|
Check before reporting done; fix every finding:
|
|
33
33
|
|
|
@@ -49,12 +49,20 @@ It exits with 1 when anything is found. Checks turned off in the config (`rules.
|
|
|
49
49
|
|
|
50
50
|
```ts
|
|
51
51
|
export class Order extends domainType(
|
|
52
|
-
z.object({
|
|
52
|
+
z.object({
|
|
53
|
+
id: z.instanceof(OrderId),
|
|
54
|
+
lines: z.array(z.instanceof(OrderLine)),
|
|
55
|
+
status: z.enum(["open", "paid"]),
|
|
56
|
+
}),
|
|
53
57
|
) {
|
|
54
|
-
|
|
55
|
-
if (this.status ===
|
|
56
|
-
|
|
57
|
-
|
|
58
|
+
withPayment = () => {
|
|
59
|
+
if (this.status === "paid") {
|
|
60
|
+
throw new AlreadyPaidOrderSalesError({
|
|
61
|
+
id: this.id.snapshot,
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
return this.with({ status: "paid" });
|
|
65
|
+
};
|
|
58
66
|
}
|
|
59
67
|
```
|
|
60
68
|
|
|
@@ -66,21 +74,24 @@ export class Order extends domainType(
|
|
|
66
74
|
|
|
67
75
|
## Application
|
|
68
76
|
|
|
69
|
-
- Use cases, commands, queries ({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.
|
|
70
|
-
- A query only reads: it never changes data (not even idempotently) and never uses a command;
|
|
77
|
+
- Use cases, commands, queries ({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. Commands and queries: the abstract contract holds the static schemas and `abstract handle`; each infrastructure implementation defines `handle` with the contract's schemas and writes only its `handler` callback. A command or query implementation performs one atomic operation: one database operation (one transaction at most), one API request; no business logic and no steps around it. Its only wired dependencies are infrastructure services (the client it runs on); repositories, ports and domain services stay with the use case. Needing more → it's several commands/queries, composed in the use case (in an application service only when 2+ use cases share that composition). Call with `x.handle(input)` (returns a result) or `x.handle.unsafe(input)` (throws).
|
|
78
|
+
- A query only reads: it never changes data (not even idempotently) and never uses a command; see "Commonly confused" in `df-ps-scaffold/references/choosing-components.md`. A command returns nothing or only the minimum needed to use its result later (e.g. the created ID), in its output schema; data to show after it comes from a query.
|
|
71
79
|
- Ports: abstract members in the port, one implementation per adapter (`api` real, `mock`/`fake` deterministic). Use the shared `clock` port instead of `new Date()`.
|
|
72
|
-
- Services: what each kind may contain and call is in `choosing-components.md` (steps
|
|
80
|
+
- Services: what each kind may contain and call is in `choosing-components.md` (steps 12–15, "Port or service?"). Domain services take and return domain types. Application services have no `handle`.
|
|
73
81
|
|
|
74
82
|
## Wiring ({wire})
|
|
75
83
|
|
|
76
84
|
Dependencies (constructor parameters and their wires) are added only by `df-ps` (`df-ps-scaffold`, rule 3): the generator's `Dependencies:` step or `Wire dependency`. It keeps each `wireClass(X, [...])` in the order of the constructor, which TypeScript checks:
|
|
77
85
|
|
|
78
86
|
```ts
|
|
79
|
-
export const wirePlaceOrderUseCase = wireClass(PlaceOrderUseCase, [
|
|
87
|
+
export const wirePlaceOrderUseCase = wireClass(PlaceOrderUseCase, [
|
|
88
|
+
wireOrderRepository,
|
|
89
|
+
wirePaymentGateway,
|
|
90
|
+
]);
|
|
80
91
|
```
|
|
81
92
|
|
|
82
93
|
- Use the injected dependencies in the class body; don't edit the parameter list or the wire list.
|
|
83
|
-
- Env-branched files (repositories,
|
|
94
|
+
- Env-branched files (repositories, commands/queries, ports): each `wire<Impl>Implementation` has its own dependencies, added per implementation. `NODE_ENV=test` selects the test one; vitest sets it.
|
|
84
95
|
- External clients and config values: an infrastructure service named after the implementation label creates or reads them (`readonly client = new PrismaClient()`); wrap its wire in `memoWire(...)` when the instance must be shared. Implementations depend on that service, never on a `wireValue(...)`.
|
|
85
96
|
- A needed dependency the CLI doesn't offer: see rule 3 (change the design).
|
|
86
97
|
|
|
@@ -30,7 +30,7 @@ Split the request into pieces of logic and choose each piece's component with `d
|
|
|
30
30
|
1. A component goes where the data and rules it depends on live.
|
|
31
31
|
2. Extend an existing context when the concept fits its language and lifecycle (the normal case).
|
|
32
32
|
3. Create a new context only for a concept with its own lifecycle and vocabulary, or a different business owner. Never one context per feature.
|
|
33
|
-
4. Contexts are fully isolated and never import each other, so each can become its own service. Every need for another context's data or behavior is
|
|
33
|
+
4. Contexts are fully isolated and never import each other, so each can become its own service. Every need for another context's data or behavior is a **query or command** in the consuming context, with its own duplicated models, implemented the simplest available way. Find it in the code:
|
|
34
34
|
- Both contexts use the same database → query it directly (the persistence label, e.g. `prisma`).
|
|
35
35
|
- Otherwise, look for the ways the project already reaches a context besides its REST endpoints: message queue, RPC, events, generated API clients. Several options (REST counts) → ask the user which one in "Decisions for you", with a recommendation. Never pick silently.
|
|
36
36
|
- Nothing besides REST → the providing context's REST endpoint (`http`).
|
|
@@ -46,7 +46,7 @@ If two placements are plausible, ask the user and give your recommendation.
|
|
|
46
46
|
Find out why, then act:
|
|
47
47
|
|
|
48
48
|
- **You don't understand the domain** (unknown term, unclear who changes the data). Ask business questions, not "which context?": Who changes it, and when? What rule does it protect? What changes together with it? Who decides when the rule changes? The answers point to the owner. Check whether the code already has the concept under another name.
|
|
49
|
-
- **The logic spans several contexts** (e.g. "cancel only if not shipped and refunded"). It's a process: each context owns its part, and the initiating context gets the coordinating use case and reaches the others through its own
|
|
49
|
+
- **The logic spans several contexts** (e.g. "cancel only if not shipped and refunded"). It's a process: each context owns its part, and the initiating context gets the coordinating use case and reaches the others through its own queries and commands.
|
|
50
50
|
- **Nobody knows, including the user.** Pick a reversible default: the initiating or closest context, other contexts behind its own queries and commands, and mark it **(provisional)** with the reason.
|
|
51
51
|
|
|
52
52
|
Never: pick silently, put one context's domain logic in `shared/`, create a catch-all context (`common`, `core`, `misc`), or split arbitrarily.
|
|
@@ -62,7 +62,7 @@ One message: the architectural part plus the work plan in the `df-ps-scaffold` r
|
|
|
62
62
|
**Work plan**
|
|
63
63
|
(df-ps-scaffold format: new contexts first; mark (new) and (provisional))
|
|
64
64
|
|
|
65
|
-
**Why:** own lifecycle and vocabulary → own context (step 3, rule 3); review → aggregate (choosing-components, step 4). "Only buyers" needs `sales` data →
|
|
65
|
+
**Why:** own lifecycle and vocabulary → own context (step 3, rule 3); review → aggregate (choosing-components, step 4). "Only buyers" needs `sales` data → query `customer-purchase` in `reviews` with its own models, implementation `prisma`: same database, so no `sales` endpoint is needed (choosing-components, step 9; step 3, rule 4).
|
|
66
66
|
|
|
67
67
|
**Decisions for you:**
|
|
68
68
|
1. Separate `reviews` context (recommended) or part of `catalog`?
|
|
@@ -25,7 +25,7 @@ Config: `shared/infrastructure/prisma/prisma.config.ts`. Source: `shared/infrast
|
|
|
25
25
|
|
|
26
26
|
### When to migrate
|
|
27
27
|
|
|
28
|
-
Only when domain and application logic are implemented, and implementing an infrastructure module (repository,
|
|
28
|
+
Only when domain and application logic are implemented, and implementing an infrastructure module (repository, command/query) needs data the database doesn't have yet. Not earlier "just in case", and never as the first step of a feature: the domain decides what's stored, not the schema.
|
|
29
29
|
|
|
30
30
|
Order: domain → application → `contract.prisma` + migration → user applies it → infrastructure → endpoints → other codegen → React.
|
|
31
31
|
|
|
@@ -82,7 +82,7 @@ Moving or renaming a page or widget is a df-ps run too (`Move or rename page` /
|
|
|
82
82
|
With `@domain-first/wire`, every new dependency of a wired class (a constructor parameter plus its wire) is added by `df-ps`: the generator's `Dependencies:` step for a new module, `Wire dependency` for an existing one, and the `Handler:` pick for an endpoint (its generator is added automatically). Don't add constructor parameters or wire entries by hand, and don't reorder or remove the ones `df-ps` added.
|
|
83
83
|
|
|
84
84
|
- List each module's dependencies in the plan as run options (`deps: OrderRepository`), with a `Wire dependency` run for existing modules.
|
|
85
|
-
- A dependency the CLI doesn't offer is forbidden by the project's dependency rules (the defaults, changed by `rules.dependencies` in the config) or by context isolation: change the design (a port,
|
|
85
|
+
- A dependency the CLI doesn't offer is forbidden by the project's dependency rules (the defaults, changed by `rules.dependencies` in the config) or by context isolation: change the design (a port, a query or command, an infrastructure service) instead of adding it by hand.
|
|
86
86
|
- A value that isn't a wired module (a database or SDK client, a config value) lives in an infrastructure service named after the implementation label (`prisma`, `in-memory-db`, `stripe`): the service creates or reads it itself (`readonly client = new PrismaClient()`), with no constructor parameter for it. Implementations get the service through `df-ps`, where it shows up under `Suggested`. Wrap the service's wire in `memoWire(...)` when one instance must be shared (a connection pool, an in-memory store). No `wireValue(...)`. A domain or application module never gets such a value directly: it depends on a port whose adapter uses the service.
|
|
87
87
|
- An endpoint generated with `handler: never` gets its handler by re-running the endpoint generator once the handler exists, as an approved overwrite.
|
|
88
88
|
|
|
@@ -95,7 +95,7 @@ Details and the check script: `df-ps-implement`, "Bounded context isolation".
|
|
|
95
95
|
- **Contexts**: subfolders of `<rootFolder>/bounded-contexts/` (menu: `Bounded Context: <name>`).
|
|
96
96
|
- **Names**: lowercase kebab-case, no generator suffix (`place-order`, not `place-order-use-case`). No empty segments (`a--b`). Pages and widgets only: folders before the name, each segment kebab-case (`admin/users`); when to nest: `references/choosing-components.md`.
|
|
97
97
|
- **Collisions**: before writing, the CLI asks `Overwrite them?` if the run would replace existing files. Check the target paths; rename, or flag the overwrite in the plan and end that run's steps with `yes`.
|
|
98
|
-
- **Tests**: with `testingLibrary` set, df-ps always generates specs; add a test implementation (`in-memory`/`mock`) to repositories,
|
|
98
|
+
- **Tests**: with `testingLibrary` set, df-ps always generates specs; add a test implementation (`in-memory`/`mock`) to repositories, commands/queries, and ports. Otherwise the spec wires the real one. Without `testingLibrary`, tell the user once and suggest adding it; don't edit the config yourself.
|
|
99
99
|
- **Prompts**: take the exact sequence for the generator and config from `references/generators.md`.
|
|
100
100
|
|
|
101
101
|
## Running the driver
|
|
@@ -16,27 +16,27 @@ Split the request into pieces of logic (one responsibility each). For each piece
|
|
|
16
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 Layer |
|
|
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
|
-
| 9 | Data or behavior of **another context**? | **
|
|
19
|
+
| 9 | Data or behavior of **another context**? | **Query** (read) / **command** (write) in this context, one per atomic operation (see below) |
|
|
20
20
|
| 10 | Leaves this context's code and storage: external system or time? | **Port** (+ adapters) |
|
|
21
|
-
| 11 | One read/write on this context's own storage that isn't "load/save one aggregate" (read model, report, bulk update)? | **
|
|
22
|
-
| 12 | A
|
|
23
|
-
| 13 |
|
|
24
|
-
| 14 |
|
|
25
|
-
| 15 | A
|
|
26
|
-
| 16 | A helper used only by presentation code? | **Presentation service** |
|
|
21
|
+
| 11 | One atomic read/write on this context's own storage that isn't "load/save one aggregate" (read model, report, bulk update)? | **Command** (write) / **query** (read) |
|
|
22
|
+
| 12 | A rule at the junction of several entities / value objects not all belonging to one aggregate (a discount from purchase history and the current discount), no I/O? | **Domain service**, always. It takes the aggregates and values it needs as arguments; loading them is the caller's job (use case, application service) |
|
|
23
|
+
| 13 | Application logic reused by 2+ use cases, with any external interaction or storage access delegated to injected ports, commands or queries? | **Application service** |
|
|
24
|
+
| 14 | A technical helper used only by infrastructure code? | **Infrastructure service** |
|
|
25
|
+
| 15 | A helper used only by presentation code? | **Presentation service** |
|
|
27
26
|
| — | None of the above | A method or function in an existing file |
|
|
28
27
|
|
|
29
|
-
- 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
|
|
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.
|
|
30
29
|
- Loading/saving one aggregate = a **repository method**, not a query or command.
|
|
31
|
-
- **
|
|
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 an external API or another context's endpoint, one message sent. 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
|
+
- **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
|
-
- Steps 9–10 beat 11–
|
|
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**.
|
|
34
34
|
- Another context (step 9): input/output are this context's own models, duplicated in its terms, never the other context's. The implementation reaches the other context the simplest available way: a shared database → directly (the persistence label, e.g. `prisma`); otherwise the way chosen by `df-ps-plan-feature` (step 3, rule 4): if the project has several ways to reach a context (REST, message queue, RPC…), ask the user; with REST only, its REST endpoint (`http`). The test implementation returns fixed data. No imports from the other context.
|
|
35
35
|
- Don't create components "just in case": a command only when storage access deserves its own contract, an application service only when reused.
|
|
36
36
|
|
|
37
37
|
## Port or service?
|
|
38
38
|
|
|
39
|
-
- A **port** describes a capability at the boundary: an external system or time. Its adapter performs the actual interaction. Own storage still follows the repository /
|
|
39
|
+
- A **port** describes a capability at the boundary: an external system or time. Its adapter performs the actual interaction. Own storage still follows the repository / command / query rules above. Another context is not a port: it's a query/command (step 9).
|
|
40
40
|
- An **application service** contains reusable application logic and may call injected ports, commands and queries. It does not call external SDKs, HTTP clients, or another context directly. A domain service remains pure: no I/O, ports, or repositories, not even injected ones; it works with the data it is handed.
|
|
41
41
|
- Wanting to mock a class or imagining multiple implementations is not enough to make it a port. Identify the boundary capability first. Ports get swappable adapters and a test implementation under `NODE_ENV=test`; test a service's logic with fake dependencies.
|
|
42
42
|
|
|
@@ -47,16 +47,14 @@ Example: `order-confirmation` prepares a message and calls the injected `mailer`
|
|
|
47
47
|
| Pair | Rule |
|
|
48
48
|
| --- | --- |
|
|
49
49
|
| Port / repository | Own aggregate's persistence → repository. External system → port. |
|
|
50
|
-
| Port /
|
|
51
|
-
| 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.
|
|
50
|
+
| Port / command, query | Own storage or another context → command/query. External system → port. |
|
|
51
|
+
| 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
52
|
| 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
53
|
| Domain / application service | Stated without requests, permissions, responses, scenarios → domain. Otherwise application. |
|
|
54
|
-
| Use case / application service | Use case = one action with `handle
|
|
55
|
-
| Use case / orchestrator | Use case = one complete business action, never reused by other use cases. Orchestrator = reusable read/write composed of execution commands/queries. Both are handlers an endpoint can use directly. |
|
|
56
|
-
| Orchestrator / application service | Only composes commands/queries into one reusable storage operation → orchestrator. Also needs ports or application logic beyond that composition → application service (it may call commands and queries, orchestrators included). |
|
|
54
|
+
| 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. |
|
|
57
55
|
| Application / infrastructure service | Used by use cases → application. Only by adapters/repositories → infrastructure. |
|
|
58
56
|
| 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. |
|
|
59
|
-
| Clock | Always a port (`clock`, usually in Shared Layer). |
|
|
57
|
+
| Clock | Always a port (`clock`, usually in Shared Layer). A command or query never uses it: the use case reads the time and passes it in the input. |
|
|
60
58
|
|
|
61
59
|
## React page, widget, UI-kit component or shared hook
|
|
62
60
|
|
|
@@ -83,8 +81,8 @@ Default **`with separated ui`**. Use `headless` only when consumers must supply
|
|
|
83
81
|
## Where it goes
|
|
84
82
|
|
|
85
83
|
- Default: the context that owns the data and rules (`df-ps-plan-feature`, step 3).
|
|
86
|
-
- Shared Layer: 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 Layer 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
|
|
87
|
-
- Another context's data or behavior →
|
|
84
|
+
- Shared Layer: 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 Layer 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
|
+
- Another context's data or behavior → a query/command in the consuming context (step 9).
|
|
88
86
|
|
|
89
87
|
## Example
|
|
90
88
|
|
|
@@ -98,7 +96,7 @@ Default **`with separated ui`**. Use `headless` only when consumers must supply
|
|
|
98
96
|
| "Can't pay twice" | 7 | `Order.pay()` |
|
|
99
97
|
| Discount ≤ 30% | 7 | `Order.applyDiscount()`: a rule about one aggregate's state; the use case passes the discount it got from the query |
|
|
100
98
|
| Place order, reorder | 8 | use cases `place-order`, `reorder` |
|
|
101
|
-
| Promo code check | 9 |
|
|
99
|
+
| Promo code check | 9 | query `promo-code-discount`: `prisma` if `marketing` shares the database, otherwise `http` to its endpoint |
|
|
102
100
|
| Email, order date | 10 | ports `mailer`, `clock` (Shared Layer) |
|
|
103
101
|
| Free shipping for gold customers | 13 | domain service `shipping-policy`: takes `customer` and `order`, no I/O |
|
|
104
102
|
| Confirmation for both use cases | 14 | application service `order-confirmation` (gets `mailer`) |
|
|
@@ -6,7 +6,7 @@ Every step list starts with `"pick:Bounded Context: <ctx>"` or `"pick:Shared Lay
|
|
|
6
6
|
|
|
7
7
|
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.
|
|
8
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,
|
|
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
10
|
|
|
11
11
|
## Bounded context
|
|
12
12
|
|
|
@@ -69,20 +69,16 @@ Prompts: name. `… pick:Application "pick:New Use Case" text:place-order`
|
|
|
69
69
|
|
|
70
70
|
## Application → New Command / New Query (context only)
|
|
71
71
|
|
|
72
|
-
Prompts: name →
|
|
72
|
+
Prompts: name → implementation (default = config persistence label) → `Add a test implementation` → if yes: test implementation (default `in-memory`).
|
|
73
73
|
|
|
74
|
-
`… pick:Application "pick:New Command" text:place-order
|
|
75
|
-
`… pick:Application "pick:New Query" text:order-summary
|
|
74
|
+
`… pick:Application "pick:New Command" text:place-order default yes default`
|
|
75
|
+
`… pick:Application "pick:New Query" text:order-summary default no`
|
|
76
76
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
- `<C>/application/commands/execution/n-command.ts`: abstract `NCommand` ({handlers} schemas + abstract `handle: Handler<…>`), spec
|
|
77
|
+
- `<C>/application/commands/n-command.ts`: abstract `NCommand` ({handlers} schemas + abstract `handle: Handler<…>`), spec
|
|
80
78
|
- `<C>/infrastructure/commands/I/I-n-command.ts` per implementation (`extends NCommand`, implements `handle`)
|
|
81
79
|
- {wire} `<C>/wiring/commands/wire-n-command.ts` (env-branched)
|
|
82
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.
|
|
83
81
|
|
|
84
|
-
Orchestrator: `<C>/application/commands/orchestration/n-command.ts` (concrete class), spec, {wire} `wire-n-command.ts`.
|
|
85
|
-
|
|
86
82
|
Queries: the same with `query` / `queries`.
|
|
87
83
|
|
|
88
84
|
## Application → New Port (context and Shared Layer)
|
|
@@ -230,8 +226,7 @@ Without wire: import `<Class>` from `<noWire>`, use `new <Class>()` and the test
|
|
|
230
226
|
| Repository* | `n-repository.ts` | `NRepository` / `vRepository` | `../../../wiring/repositories/wire-n-repository` | `n words repository` | `INRepository` `../../../infrastructure/repositories/I/I-n-repository`, `can be created via constructor` |
|
|
231
227
|
| Service | `n-L-service.ts` | `NLService` / `vLService` | `../../wiring/L-services/wire-n-L-service` | `n words` | `NLService` `./n-L-service`, `can be created` |
|
|
232
228
|
| Use case | `n-use-case.ts` | `NUseCase` / `vUseCase` | `../../wiring/use-cases/wire-n-use-case` | `n words use case` | `NUseCase` `./n-use-case`, `can be created` |
|
|
233
|
-
|
|
|
234
|
-
| Orchestrator command | `orchestration/n-command.ts` | `NCommand` / `vCommand` | `../../../wiring/commands/wire-n-command` | `n words command` | `NCommand` `./n-command`, `can be created via constructor` |
|
|
229
|
+
| Command | `n-command.ts` | `NCommand` / `vCommand` | `../../wiring/commands/wire-n-command` | `n words command` | `INCommand` `../../infrastructure/commands/I/I-n-command`, `can be created via constructor` |
|
|
235
230
|
| Port | `n.ts` | `N` / `v` | `../../wiring/application-ports/wire-n` | `n words` | `IN` `../../infrastructure/application-adapters/I/I-n`, `can be created via constructor` |
|
|
236
231
|
|
|
237
232
|
Entities and value objects (`n.entity.ts`, `n.value-object.ts`) follow the aggregate root row. `n words` = the name with spaces instead of hyphens. Queries are the same as commands. \*The repository spec imports the wire first, then `import type { NRepository } from './n-repository'`.
|