@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
package/README.md
CHANGED
|
@@ -17,7 +17,8 @@ Domain First Project Structure removes that choice: **the cleanest path is also
|
|
|
17
17
|
|
|
18
18
|
```
|
|
19
19
|
npm i -D @domain-first/project-structure
|
|
20
|
-
npx df-
|
|
20
|
+
npx df-init
|
|
21
|
+
npx df-scaffold
|
|
21
22
|
```
|
|
22
23
|
|
|
23
24
|
## API
|
|
@@ -28,10 +29,10 @@ The full technical specification lives in [API.md](./API.md).
|
|
|
28
29
|
|
|
29
30
|
### How to initialize a project
|
|
30
31
|
|
|
31
|
-
Run `df-
|
|
32
|
+
Run `df-init` in a project with a `package.json`. It asks for the source folder, the `@domain-first` packages you use, the default persistence implementation, whether to scaffold a shared in-memory DB for test implementations, React, Storybook and the testing library, then writes `domain-first.project-structure.config.json` and the Shared Kernel files these answers need. With `@domain-first/handlers-rest`, it also scaffolds the [endpoint generator](#how-to-add-a-rest-endpoint); if `next` is among your dependencies, it offers to connect `nextAdapter` from `@domain-first/handlers-next` right away and adds the catch-all route `app/api/[...path]/route.ts`. Finally it prints one command that installs the missing packages.
|
|
32
33
|
|
|
33
34
|
```
|
|
34
|
-
npx df-
|
|
35
|
+
npx df-init
|
|
35
36
|
```
|
|
36
37
|
|
|
37
38
|
```json
|
|
@@ -50,15 +51,11 @@ npx df-ps
|
|
|
50
51
|
}
|
|
51
52
|
```
|
|
52
53
|
|
|
53
|
-
Commit the config to share it with your team. Every
|
|
54
|
+
Commit the config to share it with your team. `df-init` runs once: with a config in place it exits with an error. Change the config by hand; add the endpoint generator or the in-memory DB later with [`df-integration`](#how-to-add-tooling). The other commands need the config and point to `df-init` without it. Every `df-scaffold` run performs one operation from the menu.
|
|
54
55
|
|
|
55
56
|
### How to create a bounded context
|
|
56
57
|
|
|
57
|
-
Choose **Scaffold new bounded context** and enter a name, such as `sales`.
|
|
58
|
-
|
|
59
|
-
```text
|
|
60
|
-
src/bounded-contexts/sales/domain/errors/index.ts // SalesErrors = errorNamespace('sales')
|
|
61
|
-
```
|
|
58
|
+
Choose **Scaffold new bounded context** and enter a name, such as `sales`. It starts empty: no error namespace until the first error.
|
|
62
59
|
|
|
63
60
|
Use lowercase kebab-case for every name: `place-order` becomes `PlaceOrderUseCase`.
|
|
64
61
|
|
|
@@ -119,7 +116,7 @@ Tests get the test implementation, everything else gets the primary one.
|
|
|
119
116
|
|
|
120
117
|
### How to wire dependencies
|
|
121
118
|
|
|
122
|
-
As the last step, generators with wiring offer the modules the new one may depend on, from the same bounded context and the Shared
|
|
119
|
+
As the last step, generators with wiring offer the modules the new one may depend on, from the same bounded context and the Shared Kernel. Each choice is added to the factory and to the constructor:
|
|
123
120
|
|
|
124
121
|
```ts
|
|
125
122
|
export class PlaceOrderUseCase {
|
|
@@ -135,17 +132,17 @@ Only the dependencies that respect the layers are offered: a use case can't take
|
|
|
135
132
|
|
|
136
133
|
### How to add errors
|
|
137
134
|
|
|
138
|
-
Choose **Domain → Errors** to add an error to the context namespace, create a nested namespace, or add an error to it.
|
|
135
|
+
Choose **Domain → Errors** to add an error to the context namespace, create a nested namespace, or add an error to it. The context namespace (`SalesErrors = errorNamespace('sales')` in `domain/errors/index.ts`) is created with the first error added without a namespace.
|
|
139
136
|
|
|
140
137
|
```ts
|
|
141
138
|
export class OutOfStock extends SalesErrors.define('out-of-stock') {}
|
|
142
139
|
```
|
|
143
140
|
|
|
144
|
-
Names don't repeat the context: an error of the `payment` namespace in `sales` is `PaymentDeclined`. In the Shared
|
|
141
|
+
Names don't repeat the context: an error of the `payment` namespace in `sales` is `PaymentDeclined`. In the Shared Kernel they end with `SharedKernelError`: `TimeoutSharedKernelError`.
|
|
145
142
|
|
|
146
143
|
### How to share code between contexts
|
|
147
144
|
|
|
148
|
-
Bounded contexts don't import each other. Put cross-context errors, entities, value objects, ports and services into the **Shared
|
|
145
|
+
Bounded contexts don't import each other. Put cross-context errors, entities, value objects, ports and services into the **Shared Kernel** (`src/shared-kernel`). Its modules are offered as dependencies in every context.
|
|
149
146
|
|
|
150
147
|
### How to add a REST endpoint
|
|
151
148
|
|
|
@@ -155,7 +152,7 @@ With `@domain-first/handlers-rest`, choose **Presentation → New Handlers-REST
|
|
|
155
152
|
src/bounded-contexts/sales/presentation/rest/orders/recent/GET.ts // GET /sales/orders/recent
|
|
156
153
|
```
|
|
157
154
|
|
|
158
|
-
Every endpoint uses the one endpoint generator of the project, `RestEndpointGeneratorPresentationService` in `src/shared/presentation/services/`. Initialization scaffolds it as a regular Shared
|
|
155
|
+
Every endpoint uses the one endpoint generator of the project, `RestEndpointGeneratorPresentationService` in `src/shared-kernel/presentation/services/`. Initialization scaffolds it as a regular Shared Kernel presentation service (class, spec and wire):
|
|
159
156
|
|
|
160
157
|
```ts
|
|
161
158
|
/**
|
|
@@ -172,13 +169,13 @@ export class RestEndpointGeneratorPresentationService {
|
|
|
172
169
|
}
|
|
173
170
|
```
|
|
174
171
|
|
|
175
|
-
Set the module-level `adapter` constant above the class to the adapter of your HTTP framework; the class uses it through closure. If you connected the Next adapter
|
|
172
|
+
Set the module-level `adapter` constant above the class to the adapter of your HTTP framework; the class uses it through closure. If you connected the Next adapter, the file imports `nextAdapter` from `@domain-first/handlers-next` instead, with nothing to set, and `app/api/[...path]/route.ts` (`src/app/…` when that folder exists) serves the endpoints with `nextEndpoints`. With wiring, the route serves `restHandlers`, so every new endpoint works without touching it; before the first endpoint the route doesn't compile, and the CLI says so. Each generating method is a getter returning `EndpointGenerator`: add one per kind of endpoint (for example `withAuth`, with its `context` and error mappings). Keep `invalidRequest()` of `@domain-first/handlers-rest` there for invalid requests (`400`) and add your own mappings: `errors: [httpError(MyError, 404), invalidRequest()]`. A new endpoint calls `this.endpointGenerator(...)` and doesn't compile on purpose: choose the getter yourself in its `get handle()`, e.g. `this.endpointGenerator.withoutGuards(...)`.
|
|
176
173
|
|
|
177
174
|
With wiring, the endpoint takes the generator and a handler you pick from the context's queries, commands and use cases, and all endpoints are collected as `restHandlers` in `src/presentation/rest/index.ts`. Connect them to your HTTP server.
|
|
178
175
|
|
|
179
176
|
### How to scaffold React modules
|
|
180
177
|
|
|
181
|
-
With `useReact`,
|
|
178
|
+
With `useReact`, run `npx df-react`: pages, widgets (monolithic, with separated UI, or headless), UI-kit components with Storybook stories, and shared hooks. Names may include folders:
|
|
182
179
|
|
|
183
180
|
```text
|
|
184
181
|
admin/panel/users → pages/admin/panel/admin-panel-users-page.tsx (AdminPanelUsersPage)
|
|
@@ -188,9 +185,9 @@ admin/panel/users → pages/admin/panel/admin-panel-users-page.tsx (AdminPane
|
|
|
188
185
|
|
|
189
186
|
### How to add tooling
|
|
190
187
|
|
|
191
|
-
|
|
188
|
+
Run `npx df-integration` to configure one or several of the REST endpoint generator, the shared in-memory DB, Storybook, Prisma 8, Vitest, Playwright, integration tests on PostgreSQL in Testcontainers, OpenAPI generation or an Orval API client (typed client and React Query hooks). Integrations add config files, package scripts and `.gitignore` entries, then print one install command to copy. Nothing is installed or run for you.
|
|
192
189
|
|
|
193
|
-
|
|
190
|
+
The endpoint generator and the in-memory DB are what `df-init` scaffolds; as integrations they add them later or restore missing files, and never overwrite existing ones.
|
|
194
191
|
|
|
195
192
|
### How to check the rules
|
|
196
193
|
|
|
@@ -200,11 +197,11 @@ npx df-lint
|
|
|
200
197
|
|
|
201
198
|
It reports what breaks the Domain-First rules: imports between bounded contexts, imports against the layers, modules using kinds the dependency rules don't allow (in imports and in wiring), React modules importing what they shouldn't, and reading the time without the clock port. It exits with 1 when something is found, so you can run it in CI.
|
|
202
199
|
|
|
203
|
-
The rules are a default. Teams that work differently change them in the config: what each kind of module may depend on (`rules.dependencies`) and which checks run (`rules.lint`). `df-
|
|
200
|
+
The rules are a default. Teams that work differently change them in the config: what each kind of module may depend on (`rules.dependencies`) and which checks run (`rules.lint`). `df-scaffold` offers dependencies by the same rules. Without `rules`, the defaults apply and every check runs; kinds and checks you don't mention keep their defaults.
|
|
204
201
|
|
|
205
202
|
- Kinds in `rules.dependencies` (as keys and in lists): `repositories`, `domain-services`, `application-ports`, `application-services`, `use-cases`, `commands`, `queries`, `infrastructure-services`, `presentation-services`.
|
|
206
203
|
- A kind's value: a list that replaces its defaults, or `{ "add": [...], "remove": [...] }`.
|
|
207
|
-
- Checks in `rules.lint`: `context-isolation`, `shared-
|
|
204
|
+
- Checks in `rules.lint`: `context-isolation`, `shared-kernel`, `layers`, `dependencies`, `react`, `clock`.
|
|
208
205
|
|
|
209
206
|
Defaults and details: [Dependency rules](API.md#dependency-rules), [`df-lint`](API.md#df-lint).
|
|
210
207
|
|
|
@@ -219,7 +216,7 @@ Defaults and details: [Dependency rules](API.md#dependency-rules), [`df-lint`](A
|
|
|
219
216
|
|
|
220
217
|
### How to teach your coding agent
|
|
221
218
|
|
|
222
|
-
The package ships skills that teach coding agents to plan features, scaffold with `df-
|
|
219
|
+
The package ships skills that teach coding agents to plan features, scaffold with `df-scaffold`, build the React part with `df-react` and implement the generated code.
|
|
223
220
|
|
|
224
221
|
```
|
|
225
222
|
npx df-skills --claude
|
package/dist/201.js
CHANGED
|
@@ -123,6 +123,17 @@ const pendingDeletions = new Map();
|
|
|
123
123
|
const filesToOverwrite = ()=>[
|
|
124
124
|
...pendingFiles
|
|
125
125
|
].filter(([filePath, { replacesFile }])=>replacesFile && node_fs.existsSync(filePath)).map(([filePath])=>filePath);
|
|
126
|
+
const withoutOverwrites = (generate)=>{
|
|
127
|
+
const before = new Map(pendingFiles);
|
|
128
|
+
const result = generate();
|
|
129
|
+
for (const [filePath, change] of pendingFiles){
|
|
130
|
+
if (before.get(filePath) === change || !change.replacesFile || !node_fs.existsSync(filePath)) continue;
|
|
131
|
+
const previous = before.get(filePath);
|
|
132
|
+
if (previous) pendingFiles.set(filePath, previous);
|
|
133
|
+
else pendingFiles.delete(filePath);
|
|
134
|
+
}
|
|
135
|
+
return result;
|
|
136
|
+
};
|
|
126
137
|
const discardPendingChanges = ()=>{
|
|
127
138
|
pendingFolders.clear();
|
|
128
139
|
pendingFiles.clear();
|
|
@@ -267,7 +278,7 @@ class ProjectRoot {
|
|
|
267
278
|
}
|
|
268
279
|
const lintChecks = [
|
|
269
280
|
'context-isolation',
|
|
270
|
-
'shared-
|
|
281
|
+
'shared-kernel',
|
|
271
282
|
'layers',
|
|
272
283
|
'dependencies',
|
|
273
284
|
'react',
|
|
@@ -316,39 +327,6 @@ class ConfigFile {
|
|
|
316
327
|
};
|
|
317
328
|
}
|
|
318
329
|
const configuredDependencyRules = ()=>resolveDependencyRules(ConfigFile.exists ? ConfigFile.Instance.data.rules?.dependencies : void 0);
|
|
319
|
-
const stripJsonComments = (source)=>source.replace(/("(?:\\.|[^"\\])*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (_, text)=>text ? text : '').replace(/,(\s*[}\]])/g, '$1');
|
|
320
|
-
const resolveExtends = (fromFile, target)=>{
|
|
321
|
-
if (target.startsWith('.') || node_path.isAbsolute(target)) {
|
|
322
|
-
const resolved = node_path.resolve(node_path.dirname(fromFile), target);
|
|
323
|
-
return resolved.endsWith('.json') ? resolved : `${resolved}.json`;
|
|
324
|
-
}
|
|
325
|
-
const require = createRequire(fromFile);
|
|
326
|
-
for (const candidate of [
|
|
327
|
-
target,
|
|
328
|
-
`${target}/tsconfig.json`
|
|
329
|
-
])try {
|
|
330
|
-
return require.resolve(candidate);
|
|
331
|
-
} catch {}
|
|
332
|
-
};
|
|
333
|
-
const compilerOption = (configFile, name, seen = new Set())=>{
|
|
334
|
-
if (seen.has(configFile) || !node_fs.existsSync(configFile)) return null;
|
|
335
|
-
seen.add(configFile);
|
|
336
|
-
let config;
|
|
337
|
-
try {
|
|
338
|
-
config = JSON.parse(stripJsonComments(node_fs.readFileSync(configFile, 'utf8')));
|
|
339
|
-
} catch {
|
|
340
|
-
return null;
|
|
341
|
-
}
|
|
342
|
-
if (config.compilerOptions && name in config.compilerOptions) return config.compilerOptions[name];
|
|
343
|
-
const parents = [
|
|
344
|
-
config.extends ?? []
|
|
345
|
-
].flat().reverse();
|
|
346
|
-
for (const parent of parents){
|
|
347
|
-
const parentFile = resolveExtends(configFile, parent);
|
|
348
|
-
const value = parentFile ? compilerOption(parentFile, name, seen) : null;
|
|
349
|
-
if (void 0 !== value) return value;
|
|
350
|
-
}
|
|
351
|
-
};
|
|
352
330
|
class UnknownFormatNaming {
|
|
353
331
|
rawSource;
|
|
354
332
|
camelCase;
|
|
@@ -684,4 +662,37 @@ const wireDependencies = (consumer, implementation, dependencies)=>{
|
|
|
684
662
|
for (const dependency of dependencies)classSource = addImport(classSource, `import type { ${dependency.typeName} } from '${relativeImport(implementation.file, dependency.typeFile)}'`);
|
|
685
663
|
classFile.update(addConstructorParameters(classSource, implementation.className, dependencies.map((x)=>`private readonly ${parameterName(x.typeName)}: ${x.typeName}`)));
|
|
686
664
|
};
|
|
687
|
-
|
|
665
|
+
const stripJsonComments = (source)=>source.replace(/("(?:\\.|[^"\\])*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (_, text)=>text ? text : '').replace(/,(\s*[}\]])/g, '$1');
|
|
666
|
+
const resolveExtends = (fromFile, target)=>{
|
|
667
|
+
if (target.startsWith('.') || node_path.isAbsolute(target)) {
|
|
668
|
+
const resolved = node_path.resolve(node_path.dirname(fromFile), target);
|
|
669
|
+
return resolved.endsWith('.json') ? resolved : `${resolved}.json`;
|
|
670
|
+
}
|
|
671
|
+
const require = createRequire(fromFile);
|
|
672
|
+
for (const candidate of [
|
|
673
|
+
target,
|
|
674
|
+
`${target}/tsconfig.json`
|
|
675
|
+
])try {
|
|
676
|
+
return require.resolve(candidate);
|
|
677
|
+
} catch {}
|
|
678
|
+
};
|
|
679
|
+
const compilerOption = (configFile, name, seen = new Set())=>{
|
|
680
|
+
if (seen.has(configFile) || !node_fs.existsSync(configFile)) return null;
|
|
681
|
+
seen.add(configFile);
|
|
682
|
+
let config;
|
|
683
|
+
try {
|
|
684
|
+
config = JSON.parse(stripJsonComments(node_fs.readFileSync(configFile, 'utf8')));
|
|
685
|
+
} catch {
|
|
686
|
+
return null;
|
|
687
|
+
}
|
|
688
|
+
if (config.compilerOptions && name in config.compilerOptions) return config.compilerOptions[name];
|
|
689
|
+
const parents = [
|
|
690
|
+
config.extends ?? []
|
|
691
|
+
].flat().reverse();
|
|
692
|
+
for (const parent of parents){
|
|
693
|
+
const parentFile = resolveExtends(configFile, parent);
|
|
694
|
+
const value = parentFile ? compilerOption(parentFile, name, seen) : null;
|
|
695
|
+
if (void 0 !== value) return value;
|
|
696
|
+
}
|
|
697
|
+
};
|
|
698
|
+
export { ConfigFile, File, Folder, ProjectRoot, UnknownFormatNaming, addClassMember, addConstructorParameters, addImport, addWireDependencies, availableDependencies, canDependOn, compilerOption, configuredDependencyRules, defaultDependencyRules, discardPendingChanges, fileModuleKind, filesToOverwrite, findWiredModules, implementationType, isSuggestedFor, moduleKindOf, readWiredModule, relativeImport, stripJsonComments, wireDependencies, wiredDependencyNames, withoutOverwrites, writePendingChanges };
|