@domain-first/project-structure 5.1.2 → 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 +18 -21
- package/dist/201.js +46 -35
- package/dist/287.js +3290 -0
- 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 +195 -2156
- package/dist/index.js +9 -3169
- package/dist/init.cjs +868 -0
- package/dist/init.d.ts +2 -0
- package/dist/init.js +36 -0
- package/dist/integration.cjs +2063 -0
- package/dist/integration.d.ts +2 -0
- package/dist/integration.js +31 -0
- 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/orval.d.ts +7 -4
- 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 +9 -2
- package/dist/react.cjs +915 -0
- package/dist/react.d.ts +2 -0
- package/dist/react.js +73 -0
- package/dist/use-cases/add-integration-order.spec.d.ts +1 -0
- package/dist/use-cases/rest-endpoint-generator.d.ts +1 -1
- package/package.json +5 -2
- package/skills/df-ps-implement/SKILL.md +12 -57
- package/skills/df-ps-plan-feature/SKILL.md +7 -7
- 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 +46 -28
- 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
|
@@ -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).
|
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
/**
|
|
3
|
-
* Drives
|
|
3
|
+
* Drives an interactive CLI of the package (`df-scaffold` by default, or
|
|
4
|
+
* `df-react` / `df-init` with `--bin`) with a scripted list of answers and
|
|
4
5
|
* prints the files it created or changed.
|
|
5
6
|
*
|
|
6
7
|
* Usage:
|
|
7
|
-
* node drive.mjs [--cwd <dir>] [--delay <ms>] <step> [<step> ...]
|
|
8
|
+
* node drive.mjs [--bin <name>] [--cwd <dir>] [--delay <ms>] <step> [<step> ...]
|
|
8
9
|
*
|
|
9
10
|
* Steps (one per prompt, in the order the CLI asks them):
|
|
10
11
|
* pick:<label> select prompt: type the choice label (or a unique prefix) and press Enter
|
|
@@ -22,10 +23,12 @@ import path from 'node:path';
|
|
|
22
23
|
const args = process.argv.slice(2);
|
|
23
24
|
let cwd = process.cwd();
|
|
24
25
|
let delay = 600;
|
|
26
|
+
let bin = 'df-scaffold';
|
|
25
27
|
const steps = [];
|
|
26
28
|
|
|
27
29
|
for (let i = 0; i < args.length; i++) {
|
|
28
30
|
if (args[i] === '--cwd') cwd = path.resolve(args[++i]);
|
|
31
|
+
else if (args[i] === '--bin') bin = args[++i];
|
|
29
32
|
else if (args[i] === '--delay') delay = Number(args[++i]);
|
|
30
33
|
else steps.push(args[i]);
|
|
31
34
|
}
|
|
@@ -87,12 +90,17 @@ const snapshot = () => {
|
|
|
87
90
|
return result;
|
|
88
91
|
};
|
|
89
92
|
|
|
90
|
-
|
|
93
|
+
if (!['df-scaffold', 'df-react', 'df-init'].includes(bin)) {
|
|
94
|
+
console.error(`Unknown --bin: ${bin}`);
|
|
95
|
+
process.exit(2);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
const localBin = path.join(projectRoot, 'node_modules', '.bin', bin);
|
|
91
99
|
const [command, commandArgs] = fs.existsSync(localBin)
|
|
92
100
|
? [localBin, []]
|
|
93
101
|
: [
|
|
94
102
|
'npm',
|
|
95
|
-
['exec', '--yes', '--package=@domain-first/project-structure', '--',
|
|
103
|
+
['exec', '--yes', '--package=@domain-first/project-structure', '--', bin]
|
|
96
104
|
];
|
|
97
105
|
|
|
98
106
|
const before = snapshot();
|