@domain-first/project-structure 3.3.1 → 4.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 CHANGED
@@ -166,26 +166,28 @@ const adapter = undefined as unknown as Adapter<any[], any>
166
166
  export class RestEndpointGeneratorPresentationService {
167
167
  /**
168
168
  * Default errors of a client request, to spread into a generator's
169
- * own checks.
169
+ * own error mappings.
170
170
  */
171
- private get defaultClientRequestErrors(): ErrorStatuses[number]['checks'] {
172
- return [RequestParsingError.is, InputMappingError.is]
171
+ private get defaultClientRequestErrors(): ErrorMapping[] {
172
+ return [
173
+ httpStatus(400, {
174
+ code: 'INVALID_REQUEST',
175
+ description: 'Invalid request',
176
+ message: (error) => error.message,
177
+ match: [RequestParsingError, InputMappingError]
178
+ })
179
+ ]
173
180
  }
174
181
 
175
182
  get withoutGuards(): EndpointGenerator {
176
183
  return createEndpoint({
177
- errorStatuses: {
178
- 400: {
179
- checks: this.defaultClientRequestErrors,
180
- description: 'Invalid request'
181
- }
182
- }
184
+ errors: this.defaultClientRequestErrors
183
185
  })(adapter) as EndpointGenerator
184
186
  }
185
187
  }
186
188
  ```
187
189
 
188
- 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 during initialization, the file imports `nextAdapter` from `@domain-first/handlers-next` instead, with nothing to set. Each generating method is a getter returning `EndpointGenerator`: add one per kind of endpoint (for example `withAuth`, with its `context` and error statuses). Reuse the default checks there and add your own: `checks: [...this.defaultClientRequestErrors, MyError.is]`. 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(...)`.
190
+ 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 during initialization, the file imports `nextAdapter` from `@domain-first/handlers-next` instead, with nothing to set. Each generating method is a getter returning `EndpointGenerator`: add one per kind of endpoint (for example `withAuth`, with its `context` and error mappings). Reuse the default mappings there and add your own: `errors: [httpError(MyError, 404), ...this.defaultClientRequestErrors]`. 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(...)`.
189
191
 
190
192
  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.
191
193
 
package/dist/index.cjs CHANGED
@@ -2024,8 +2024,9 @@ const scaffoldRestEndpointGenerator = (sharedFolder, { withNextAdapter = false }
2024
2024
  return `
2025
2025
  import {
2026
2026
  ${withNextAdapter ? '' : ' type Adapter,\n'} type EndpointGenerator,
2027
- type ErrorStatuses,
2027
+ type ErrorMapping,
2028
2028
  createEndpoint,
2029
+ httpStatus,
2029
2030
  InputMappingError,
2030
2031
  RequestParsingError
2031
2032
  } from '@domain-first/handlers-rest'
@@ -2038,20 +2039,22 @@ const adapter = undefined as unknown as Adapter<any[], any>`}
2038
2039
  export class ${className} {
2039
2040
  /**
2040
2041
  * Default errors of a client request, to spread into a generator's
2041
- * own checks.
2042
+ * own error mappings.
2042
2043
  */
2043
- private get defaultClientRequestErrors(): ErrorStatuses[number]['checks'] {
2044
- return [RequestParsingError.is, InputMappingError.is]
2044
+ private get defaultClientRequestErrors(): ErrorMapping[] {
2045
+ return [
2046
+ httpStatus(400, {
2047
+ code: 'INVALID_REQUEST',
2048
+ description: 'Invalid request',
2049
+ message: (error) => error.message,
2050
+ match: [RequestParsingError, InputMappingError]
2051
+ })
2052
+ ]
2045
2053
  }
2046
2054
 
2047
2055
  get withoutGuards(): EndpointGenerator {
2048
2056
  return createEndpoint({
2049
- errorStatuses: {
2050
- 400: {
2051
- checks: this.defaultClientRequestErrors,
2052
- description: 'Invalid request'
2053
- }
2054
- }
2057
+ errors: this.defaultClientRequestErrors
2055
2058
  })(${adapter}) as EndpointGenerator
2056
2059
  }
2057
2060
  }
package/dist/index.js CHANGED
@@ -1994,8 +1994,9 @@ const scaffoldRestEndpointGenerator = (sharedFolder, { withNextAdapter = false }
1994
1994
  return `
1995
1995
  import {
1996
1996
  ${withNextAdapter ? '' : ' type Adapter,\n'} type EndpointGenerator,
1997
- type ErrorStatuses,
1997
+ type ErrorMapping,
1998
1998
  createEndpoint,
1999
+ httpStatus,
1999
2000
  InputMappingError,
2000
2001
  RequestParsingError
2001
2002
  } from '@domain-first/handlers-rest'
@@ -2008,20 +2009,22 @@ const adapter = undefined as unknown as Adapter<any[], any>`}
2008
2009
  export class ${className} {
2009
2010
  /**
2010
2011
  * Default errors of a client request, to spread into a generator's
2011
- * own checks.
2012
+ * own error mappings.
2012
2013
  */
2013
- private get defaultClientRequestErrors(): ErrorStatuses[number]['checks'] {
2014
- return [RequestParsingError.is, InputMappingError.is]
2014
+ private get defaultClientRequestErrors(): ErrorMapping[] {
2015
+ return [
2016
+ httpStatus(400, {
2017
+ code: 'INVALID_REQUEST',
2018
+ description: 'Invalid request',
2019
+ message: (error) => error.message,
2020
+ match: [RequestParsingError, InputMappingError]
2021
+ })
2022
+ ]
2015
2023
  }
2016
2024
 
2017
2025
  get withoutGuards(): EndpointGenerator {
2018
2026
  return createEndpoint({
2019
- errorStatuses: {
2020
- 400: {
2021
- checks: this.defaultClientRequestErrors,
2022
- description: 'Invalid request'
2023
- }
2024
- }
2027
+ errors: this.defaultClientRequestErrors
2025
2028
  })(${adapter}) as EndpointGenerator
2026
2029
  }
2027
2030
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@domain-first/project-structure",
3
3
  "description": "Build and manage your Domain-First project structure with CLI",
4
- "version": "3.3.1",
4
+ "version": "4.0.0",
5
5
  "type": "module",
6
6
  "repository": {
7
7
  "type": "git",
@@ -23,7 +23,7 @@ A file in context A imports **nothing** from context B: no types (`import type`
23
23
  - A needs B's data or behavior → an **execution query** (read) or **execution command** (write) in A. Its input/output are A's own models, duplicated in A's terms; B's models never appear in A.
24
24
  - 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.
25
25
  - Refer to B's entities by id only.
26
- - `shared/` may import any context's **`domain/errors`** (e.g. to map them to HTTP statuses), and nothing else from a context. Don't move a context's domain concepts into `shared/` to share them between contexts; only universal entities / value objects (`money`, `email`) live there.
26
+ - `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.
27
27
  - `<rootFolder>/presentation/rest/` (the generated `wires.ts`, `index.ts`) may import every context's REST wiring.
28
28
  - `<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.
29
29
  - Need a forbidden import? A's own execution query or command is missing. Plan it and generate it.
@@ -77,7 +77,7 @@ export const wirePlaceOrderUseCase = wireClass(PlaceOrderUseCase, [wireOrderRepo
77
77
 
78
78
  ## REST endpoints ({handlers-rest})
79
79
 
80
- 1. Generator: initialization creates `RestEndpointGeneratorPresentationService` in `<rootFolder>/shared/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 initialization connected the Next adapter, the file already imports `nextAdapter` from `@domain-first/handlers-next` and passes it instead; just make sure that package is installed. The default `400` checks live in the private `defaultClientRequestErrors` getter; extend a status with `checks: [...this.defaultClientRequestErrors, MyError.is]`. Map domain errors to statuses in the generator's `errorStatuses`, importing them from the contexts' `domain/errors` (the only thing `shared/` may import from a context). A new kind of endpoint (auth, other context) is a new getter returning `createEndpoint({ context, errorStatuses })(adapter) as EndpointGenerator` (`nextAdapter` with the Next adapter), next to `withoutGuards`. Generate the exposed handler before the endpoint: with wire, the `Handler:` pick fills its type and the wire (`[wireRestEndpointGeneratorPresentationService, wireGetRecentOrdersUseCase]`).
80
+ 1. Generator: initialization creates `RestEndpointGeneratorPresentationService` in `<rootFolder>/shared/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 initialization connected the Next adapter, the file already imports `nextAdapter` from `@domain-first/handlers-next` and passes it instead; just make sure that package is installed. The default `400` mapping lives in the private `defaultClientRequestErrors` getter (`ErrorMapping[]`); extend it with `errors: [httpError(MyError, 404), ...this.defaultClientRequestErrors]`. Map domain errors to statuses in the generator's `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/` may import from a context, besides domain models in the in-memory DB). A new kind of endpoint (auth, other context) is a new getter returning `createEndpoint({ context, errors })(adapter) as EndpointGenerator` (`nextAdapter` with the Next adapter), next to `withoutGuards`. Generate the exposed handler before the endpoint: with wire, the `Handler:` pick fills its type and the wire (`[wireRestEndpointGeneratorPresentationService, wireGetRecentOrdersUseCase]`).
81
81
  2. If `handler: never` is left (no handler existed at generation), re-run the endpoint generator as an approved overwrite to pick it (rule 3); don't replace it by hand.
82
82
  3. Complete `get handle()`: the generated `this.endpointGenerator(...)` doesn't compile on purpose. Pick the generating getter that fits the endpoint (`this.endpointGenerator.withoutGuards(...)`, or one with the needed guards), then `.input(...)`, `.mapInput(...)`, optional `.output(...)`, `.mapOutput(...)`.
83
83
  4. Register `restHandlers` from `<rootFolder>/presentation/rest/index.ts` in the server bootstrap (rule 2, exception 5).
@@ -7,7 +7,10 @@
7
7
  * rootFolder defaults to `rootFolder` in domain-first.project-structure.config.json.
8
8
  *
9
9
  * Bounded contexts never import each other (no exceptions).
10
- * Allowed: shared/** may import any context's domain/errors; presentation/react/** may only
10
+ * Allowed: shared/** may import any context's domain/errors; the shared in-memory DB
11
+ * (shared/infrastructure/services/in-memory-db-infrastructure-service.ts) may also import any
12
+ * context's domain models: domain/aggregates/** (barrels included, `*-repository` files not),
13
+ * domain/entities/**, domain/value-objects/**; presentation/react/** may only
11
14
  * `import type` from a context's presentation/rest/; presentation/react/ui-kit/** imports
12
15
  * nothing from bounded contexts, widgets or pages.
13
16
  * Widgets never import each other: a file of one widget (the nearest folder under widgets/
@@ -36,6 +39,13 @@ const sharedDir = path.join(root, 'shared');
36
39
  const reactDir = path.join(root, 'presentation', 'react');
37
40
  const uiKitDir = path.join(reactDir, 'ui-kit');
38
41
  const widgetsDir = path.join(reactDir, 'widgets');
42
+ const inMemoryDbFile = path.join(sharedDir, 'infrastructure', 'services', 'in-memory-db-infrastructure-service.ts');
43
+
44
+ // Domain models of a context: aggregate roots, entities and value objects, not repository contracts.
45
+ const isDomainModel = (target, layer, part) =>
46
+ layer === 'domain' &&
47
+ ['aggregates', 'entities', 'value-objects'].includes(part) &&
48
+ !/-repository(\.tsx?)?$/.test(path.basename(target));
39
49
 
40
50
  // tsconfig `paths` → [{ prefix, wildcard, targets }]
41
51
  const readTsconfig = (file) => {
@@ -157,12 +167,13 @@ for (const file of scanned) {
157
167
  for (const imp of importsOf(file)) {
158
168
  if (!imp.target) continue;
159
169
  const [targetContext, layer, part] = inside(contextsDir, imp.target) ?? [];
170
+ const allowedInMemoryDbImport = file === inMemoryDbFile && isDomainModel(imp.target, layer, part);
160
171
 
161
172
  if (ownContext) {
162
173
  if (targetContext && targetContext !== ownContext) report(`[${ownContext}] imports another context:`, file, imp);
163
174
  } else if (inside(sharedDir, file)) {
164
- if (targetContext && !(layer === 'domain' && part === 'errors')) {
165
- report('[shared] imports a bounded context outside its domain/errors:', file, imp);
175
+ if (targetContext && !(layer === 'domain' && part === 'errors') && !allowedInMemoryDbImport) {
176
+ report('[shared] imports a bounded context outside its domain/errors (and domain models for the in-memory DB):', file, imp);
166
177
  }
167
178
  } else if (inside(uiKitDir, file)) {
168
179
  const [area] = inside(reactDir, imp.target) ?? [];