@domain-first/project-structure 2.11.0 → 2.13.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 +89 -2
- package/dist/file-system.d.ts +6 -0
- package/dist/index.cjs +872 -49
- package/dist/index.js +872 -49
- package/dist/integrations/index.d.ts +4 -0
- package/dist/integrations/missing-domain-first-packages.d.ts +1 -0
- package/dist/integrations/missing-domain-first-packages.spec.d.ts +1 -0
- package/dist/integrations/package-scripts.d.ts +2 -0
- package/dist/integrations/package-scripts.spec.d.ts +1 -0
- package/dist/integrations/prisma.d.ts +6 -0
- package/dist/integrations/prisma.spec.d.ts +1 -0
- package/dist/integrations/storybook.d.ts +9 -0
- package/dist/save-pending-changes.d.ts +2 -0
- package/dist/use-cases/add-integration.d.ts +1 -0
- package/dist/use-cases/add-integration.spec.d.ts +1 -0
- package/dist/use-cases/index.d.ts +2 -0
- package/dist/use-cases/wire-dependency.d.ts +17 -0
- package/dist/wiring.d.ts +90 -0
- package/dist/wiring.spec.d.ts +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -161,7 +161,18 @@ With `@domain-first/wire`, generators create `wireClass` factories. Repositories
|
|
|
161
161
|
| `development` | The primary implementation. Also used when `NODE_ENV` is unset. |
|
|
162
162
|
| `production` | The primary implementation. |
|
|
163
163
|
|
|
164
|
-
Implementation names such as `prisma`, `api`, `in-memory`, and `mock` determine names and locations for generated classes. Add the database queries, API calls, or in-memory behavior yourself.
|
|
164
|
+
Implementation names such as `prisma`, `api`, `in-memory`, and `mock` determine names and locations for generated classes. Add the database queries, API calls, or in-memory behavior yourself. As the last step, generators that create a wiring factory offer to pick its dependencies from wired modules of the same bounded context and the Shared Layer. Each selected module is added to the factory's dependency list and to the constructor, for example `private readonly userRepository: UserRepository`. Environment-branched factories (repositories, execution commands and queries, ports) wire each implementation in isolation: you pick dependencies separately for each one, for example for `PrismaUserRepository` and then for `InMemoryUserRepository`. Each list starts with a **Suggested** group when infrastructure modules match the implementation name: `prisma-infrastructure-service` for a `prisma` implementation, or `in-memory-db-infrastructure-service` for an `in-memory` one. To add dependencies to an existing module later, select **Wire dependency** in the bounded context or Shared Layer menu. Environment-branched modules are listed there once per implementation, such as `UserRepository (prisma)` and `UserRepository (in-memory)`, and only the chosen one is changed.
|
|
165
|
+
|
|
166
|
+
The list depends on the layer of the class being built:
|
|
167
|
+
|
|
168
|
+
| Layer | Can depend on |
|
|
169
|
+
| -------------- | -------------------------------------------- |
|
|
170
|
+
| Domain | Domain |
|
|
171
|
+
| Application | Domain, application |
|
|
172
|
+
| Infrastructure | Domain, infrastructure |
|
|
173
|
+
| Presentation | Application, presentation |
|
|
174
|
+
|
|
175
|
+
Some kinds of modules have narrower rules. From the application layer, application services can use only ports. Use cases can't use other use cases, and repository implementations can't use other repositories. Execution commands and queries can't use other commands or queries. From the application layer, orchestration commands and queries can use only execution commands and queries. Repository, execution command, execution query, and port implementations belong to infrastructure: they implement application modules but can't take them as dependencies. REST endpoints are not offered as dependencies. Their dependencies are chosen when they are generated (see REST endpoints) and are not available in **Wire dependency**.
|
|
165
176
|
|
|
166
177
|
When `testingLibrary` is configured, supported generators always add `.spec.ts` files. These start with construction or wiring checks; extend them with tests for your business behavior. Repository, command, query, and port test templates reference wiring factories, so use the wiring integration or adapt those tests to your own construction setup.
|
|
167
178
|
|
|
@@ -173,7 +184,7 @@ Select an existing controller or create one, choose `get`, `post`, `patch`, `del
|
|
|
173
184
|
src/bounded-contexts/sales/presentation/rest/orders/recent/GET.ts
|
|
174
185
|
```
|
|
175
186
|
|
|
176
|
-
The route metadata uses `/sales/orders/recent`.
|
|
187
|
+
The route metadata uses `/sales/orders/recent`. With `@domain-first/wire`, the generator then asks for the endpoint generator, picked from presentation services of the bounded context and the Shared Layer (services with `endpoint` in the name are suggested first), and for the handler, picked from queries, commands, and use cases of the bounded context. The endpoint's constructor gets the chosen types, and its wiring factory gets their factories. In `get handle()`, call the generating method of the chosen service yourself, for example `this.endpointGenerator.generate(...)` for `readonly generate = createEndpoint(...)(adapter)`. Without wiring, or when there is nothing to pick, the endpoint keeps the `EndpointGenerator` type and a `never` handler placeholder for you to replace.
|
|
177
188
|
|
|
178
189
|
With wiring enabled, the generator also adds endpoint factories and exports collected as `restHandlers` in `<rootFolder>/presentation/rest/index.ts`. Connect these handlers to your HTTP server.
|
|
179
190
|
|
|
@@ -192,6 +203,82 @@ Enable `useReact` and choose **Scaffold React module** from the main menu. Modul
|
|
|
192
203
|
|
|
193
204
|
Page and widget names can include folders split by `/`. For example, a page named `admin/panel/users` is created at `pages/admin/panel/users-page.tsx` as `AdminPanelUsersPage`, and a widget with the same name at `widgets/admin/panel/users/` as `AdminPanelUsersWidget` with the story title `Widgets/Admin/Panel/Users`. File names use only the last segment; code names use the whole path.
|
|
194
205
|
|
|
206
|
+
### Project integrations
|
|
207
|
+
|
|
208
|
+
Choose **Add integration → Storybook (React + Vite)** to configure Storybook.
|
|
209
|
+
The integration creates `main.ts` and `preview.ts` under
|
|
210
|
+
`<rootFolder>/presentation/react/.storybook`, enables React scaffolding and sets
|
|
211
|
+
`storybookFramework` to `@storybook/react-vite` for future generated stories.
|
|
212
|
+
It uses relative story paths and configures the Vite alias `@` to the absolute
|
|
213
|
+
project root (the directory containing `package.json`), computed at runtime
|
|
214
|
+
from the config location. Add project CSS to `preview.ts` with relative imports
|
|
215
|
+
or `@/` imports. The setup includes `@vitejs/plugin-react`.
|
|
216
|
+
|
|
217
|
+
It adds these package scripts, with paths adjusted to your `rootFolder`:
|
|
218
|
+
|
|
219
|
+
```json
|
|
220
|
+
{
|
|
221
|
+
"storybook": "storybook dev -p 6006 -c \"src/presentation/react/.storybook\"",
|
|
222
|
+
"build-storybook": "storybook build -c \"src/presentation/react/.storybook\" -o \"src/presentation/react/storybook-static\""
|
|
223
|
+
}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
Existing unrelated scripts and package fields are preserved. If a script name
|
|
227
|
+
already has a different command, choose to keep it, replace it, or use another
|
|
228
|
+
name. Identical generated configs and scripts are skipped on subsequent runs;
|
|
229
|
+
changed config files use the usual overwrite confirmation. Cancelling before
|
|
230
|
+
writing leaves all files unchanged.
|
|
231
|
+
|
|
232
|
+
After writing, the CLI prints npm commands for missing dependencies and the
|
|
233
|
+
selected scripts. It does not install packages or execute scripts. Install commands omit version constraints for Storybook, its React + Vite
|
|
234
|
+
framework, Vite and the React plugin; existing dependency versions are preserved
|
|
235
|
+
and must be compatible with those packages. Generate a
|
|
236
|
+
UI-kit component or a widget with separated UI to add your first story. The
|
|
237
|
+
static build goes to `<rootFolder>/presentation/react/storybook-static`.
|
|
238
|
+
|
|
239
|
+
### Missing domain-first packages
|
|
240
|
+
|
|
241
|
+
Choose **Add integration → Missing domain-first packages** to compare
|
|
242
|
+
`domainFirstPackages` in the configuration with `dependencies`, `devDependencies`
|
|
243
|
+
and `optionalDependencies` in the project's `package.json`. The CLI prints one
|
|
244
|
+
`npm i` command for missing packages, without version constraints. If none are
|
|
245
|
+
missing, it reports that all configured packages are already declared. This
|
|
246
|
+
checks declared dependencies, not the contents of `node_modules`, and does not
|
|
247
|
+
modify files or install packages.
|
|
248
|
+
|
|
249
|
+
### Prisma 8 (PostgreSQL)
|
|
250
|
+
|
|
251
|
+
Choose **Add integration → Prisma 8 (PostgreSQL, RC)**. The preset creates
|
|
252
|
+
`<rootFolder>/shared/infrastructure/prisma/prisma.config.ts` and a starter
|
|
253
|
+
`contract.prisma`. Existing contracts are preserved, including your models.
|
|
254
|
+
|
|
255
|
+
You can optionally create `PrismaInfrastructureService` in
|
|
256
|
+
`shared/infrastructure/services`; it exposes `orm`, uses the Temporal polyfill,
|
|
257
|
+
and reuses the client across development hot reloads. When `@domain-first/wire`
|
|
258
|
+
is enabled, the integration also creates its wiring factory. A separate prompt
|
|
259
|
+
lets you make `prisma` the default persistence implementation.
|
|
260
|
+
|
|
261
|
+
The integration adds three scripts, all pointing to the generated config:
|
|
262
|
+
|
|
263
|
+
- `prisma:emit`: emit `contract.json` and `contract.d.ts`.
|
|
264
|
+
- `prisma:migration:plan`: emit the contract, then plan a migration.
|
|
265
|
+
- `prisma:migration:apply`: apply migrations and advance the `db` ref.
|
|
266
|
+
|
|
267
|
+
Script conflicts use the same keep/replace/rename flow as Storybook. File changes
|
|
268
|
+
are staged until overwrite confirmation; no packages are installed and no
|
|
269
|
+
commands connect to the database during scaffolding.
|
|
270
|
+
|
|
271
|
+
The printed install commands omit version constraints for `prisma`,
|
|
272
|
+
`@prisma/cli-engine`, `@prisma/orm-postgres`, `temporal-polyfill`, and `dotenv`. Already declared dependencies are kept. This is a PostgreSQL
|
|
273
|
+
preset for Prisma 8 RC, not a Prisma 7 migration tool.
|
|
274
|
+
|
|
275
|
+
After installing dependencies, configure `DATABASE_URL` (the CLI loads `.env`;
|
|
276
|
+
your application must load its runtime environment), add your models to the
|
|
277
|
+
contract and run the emit script before compiling or importing the service.
|
|
278
|
+
Use Node.js 22.18+, TypeScript 5.9+, ESM and JSON import support. Review planned
|
|
279
|
+
migrations before running the apply script. Generated contract files and
|
|
280
|
+
migration history are managed by Prisma, not by this scaffolder.
|
|
281
|
+
|
|
195
282
|
## Configuration
|
|
196
283
|
|
|
197
284
|
The project configuration is stored in `domain-first.project-structure.config.json`. Commit it to share generation settings with your team. For example:
|
package/dist/file-system.d.ts
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
* Existing files a full rewrite would replace, whatever their content.
|
|
3
3
|
*/
|
|
4
4
|
export declare const filesToOverwrite: () => string[];
|
|
5
|
+
export declare const discardPendingChanges: () => void;
|
|
5
6
|
export declare const writePendingChanges: () => void;
|
|
6
7
|
declare class FileSystemItem {
|
|
7
8
|
readonly path: string;
|
|
@@ -23,6 +24,11 @@ export declare class File extends FileSystemItem {
|
|
|
23
24
|
get exists(): boolean;
|
|
24
25
|
get data(): string;
|
|
25
26
|
set data(content: string);
|
|
27
|
+
/**
|
|
28
|
+
* Changes the content without marking a full rewrite, so editing an
|
|
29
|
+
* existing file doesn't ask to overwrite it.
|
|
30
|
+
*/
|
|
31
|
+
update: (content: string) => void;
|
|
26
32
|
addLine: (newLine: string, separator?: string) => void;
|
|
27
33
|
/**
|
|
28
34
|
* Re-running a generator for the same name must not duplicate the line.
|