@anarchitects/nx-typeorm 0.1.0 → 0.3.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
@@ -6,6 +6,7 @@ It provides:
6
6
  - `nx add` / `init` setup for minimal TypeORM dependencies.
7
7
  - `bootstrap` scaffolding for app runtime datasource wiring and library
8
8
  infrastructure-persistence templates.
9
+ - name-first scaffold generators for TypeORM file creation workflows.
9
10
  - inferred database targets via `createNodesV2`.
10
11
  - thin executors that wrap TypeORM CLI workflows.
11
12
 
@@ -80,6 +81,83 @@ The generated helper rejects mixed mode (setting `DATABASE_URL` together with
80
81
  `TYPEORM_*` connection variables) and throws clear validation errors when
81
82
  required variables are missing.
82
83
 
84
+ ### Scaffolding generators
85
+
86
+ These are convenience wrappers around existing executors. They are invoked
87
+ manually via `nx g` and are not inferred targets.
88
+
89
+ `migration-create` (alias: `migration`)
90
+
91
+ ```bash
92
+ nx g @anarchitects/nx-typeorm:migration-create --project=api --name="add users"
93
+ nx g @anarchitects/nx-typeorm:migration --project=api --name="add users"
94
+ ```
95
+
96
+ - required: `--project`, `--name`
97
+ - optional: `--directory` (relative to project root), `--outputJs`, `--esm`,
98
+ `--timestamp`, `--args`
99
+ - default output directory:
100
+ - app: `tools/typeorm/migrations`
101
+ - lib: `src/infrastructure-persistence/migrations`
102
+
103
+ `migration-api` (alias: `migration-api-lib`)
104
+
105
+ ```bash
106
+ nx g @anarchitects/nx-typeorm:migration-api --project=data-access --name="init users"
107
+ nx g @anarchitects/nx-typeorm:migration-api-lib --project=data-access --name="init users"
108
+ ```
109
+
110
+ - library-only generator (fails for applications)
111
+ - generates migration files using TypeORM migration API (`QueryRunner`, `Table`,
112
+ `TableColumn`, etc.) without raw SQL strings
113
+ - maintains migration state in
114
+ `src/infrastructure-persistence/migrations/.nx-typeorm-migration-manifest.json`
115
+ - default behavior:
116
+ - no file when entity snapshot is unchanged
117
+ - new consolidated delta migration when entities changed
118
+ - options:
119
+ - required: `--project`
120
+ - required in `fileMode=new` (default): `--name`
121
+ - optional: `--fileMode=new|patch-init` (default `new`)
122
+ - optional: `--entityGlob=<glob-relative-to-project-root>`
123
+ (default `src/infrastructure-persistence/entities/**/*.ts`)
124
+ - optional: `--allowMixedMigrations` to opt into mixed manual/tool migration
125
+ directories
126
+ - optional: `--timestamp=<number>`
127
+ - safety behavior:
128
+ - fails on unsupported/unresolvable decorators/options
129
+ - fails when implicit naming cannot be resolved safely
130
+ - fails on rename-like table/column diffs (manual migration required)
131
+ - `patch-init` only patches bootstrap init migration
132
+ `1700000000000_init_schema.ts` and is only allowed before any generated
133
+ delta migration exists
134
+
135
+ `entity-create` (alias: `entity`)
136
+
137
+ ```bash
138
+ nx g @anarchitects/nx-typeorm:entity-create --project=api --name="user profile"
139
+ nx g @anarchitects/nx-typeorm:entity --project=api --name="user profile"
140
+ ```
141
+
142
+ - required: `--project`, `--name`
143
+ - optional: `--directory` (relative to project root), `--args`
144
+ - default output directory:
145
+ - app: `src/entities`
146
+ - lib: `src/infrastructure-persistence/entities`
147
+
148
+ `subscriber-create` (alias: `subscriber`)
149
+
150
+ ```bash
151
+ nx g @anarchitects/nx-typeorm:subscriber-create --project=api --name="user subscriber"
152
+ nx g @anarchitects/nx-typeorm:subscriber --project=api --name="user subscriber"
153
+ ```
154
+
155
+ - required: `--project`, `--name`
156
+ - optional: `--directory` (relative to project root), `--args`
157
+ - default output directory:
158
+ - app: `src/subscribers`
159
+ - lib: `src/infrastructure-persistence/subscribers`
160
+
83
161
  ## Inferred Targets
84
162
 
85
163
  When TypeORM files are detected, the plugin infers:
@@ -125,16 +203,19 @@ nx run api:db:seed --file tools/typeorm/seeds/index.ts
125
203
  `generate` supports `--check` and compatibility alias `--driftCheck` (mapped to
126
204
  TypeORM check mode).
127
205
 
128
- CLI executors (`generate`, `run`, `revert`) select the TypeORM runner at
129
- runtime:
206
+ Datasource-backed CLI executors (`generate`, `run`, `revert`,
207
+ `migration-show`, `schema-sync`, `schema-log`, `schema-drop`, `query`,
208
+ `cache-clear`) select the TypeORM runner at runtime:
130
209
 
131
210
  - `moduleSystem=auto` (default): detect by nearest `package.json` `type`,
132
211
  then project tsconfig module mode, then fall back to CommonJS.
133
212
  - `moduleSystem=commonjs`: force `typeorm-ts-node-commonjs`.
134
213
  - `moduleSystem=esm`: force `typeorm-ts-node-esm`.
135
214
 
136
- When `dataSource` is omitted, migration-oriented executors (`generate`, `run`,
137
- `revert`) and `ensure-schema` infer it from the project with this priority:
215
+ When `dataSource` is omitted, datasource-backed executors (`generate`, `run`,
216
+ `revert`, `migration-show`, `schema-sync`, `schema-log`, `schema-drop`,
217
+ `query`, `cache-clear`) and `ensure-schema` infer it from the project with
218
+ this priority:
138
219
 
139
220
  1. `tools/typeorm/datasource.migrations.ts`
140
221
  2. `tools/typeorm/datasource.migrations.js`
@@ -147,6 +228,10 @@ Override inference at any time with `--dataSource=<relative-or-absolute-path>`.
147
228
 
148
229
  ## TypeORM CLI Coverage
149
230
 
231
+ Inference is intentionally limited to convention-safe operational commands.
232
+ Scaffolding/meta commands (`migration:create`, `entity:create`,
233
+ `subscriber:create`, `version`, `init`) are executor-only and not inferred.
234
+
150
235
  | TypeORM CLI command | nx-typeorm executor | Inferred target |
151
236
  | -------------------- | ------------------- | --------------- |
152
237
  | `migration:create` | `migration-create` | no |
@@ -165,7 +250,8 @@ Override inference at any time with `--dataSource=<relative-or-absolute-path>`.
165
250
  | `init` | `init` | no |
166
251
 
167
252
  Manual-only executors are available for explicit wiring in `project.json`.
168
- This includes risky commands like `query` and `schema:drop`.
253
+ This includes risky commands (`query`, `schema:drop`) and non-inferred
254
+ scaffolding/meta commands from the table above.
169
255
 
170
256
  Example manual targets:
171
257
 
@@ -1,12 +1,16 @@
1
- import { MigrationInterface, QueryRunner } from 'typeorm';
1
+ import { MigrationInterface, QueryRunner, Table, TableCheck, TableColumn, TableExclusion, TableForeignKey, TableIndex, TableUnique } from 'typeorm';
2
2
  import { <%= className %>_SCHEMA as SCHEMA } from '../schema';
3
3
 
4
4
  export class Init<%= className %>Schema1700000000000 implements MigrationInterface {
5
- async up(q: QueryRunner): Promise<void> {
6
- await q.query(`CREATE SCHEMA IF NOT EXISTS "${SCHEMA}"`);
5
+ async up(queryRunner: QueryRunner): Promise<void> {
6
+ await queryRunner.createSchema(SCHEMA, true);
7
+ // nx-typeorm:migration-api:up:start
8
+ // nx-typeorm:migration-api:up:end
7
9
  }
8
10
 
9
11
  async down(): Promise<void> {
12
+ // nx-typeorm:migration-api:down:start
13
+ // nx-typeorm:migration-api:down:end
10
14
  // Schema intentionally kept
11
15
  }
12
16
  }
@@ -0,0 +1,4 @@
1
+ import { type Tree } from '@nx/devkit';
2
+ import type { EntityCreateGeneratorSchema } from './schema.js';
3
+ export default function entityCreateGenerator(tree: Tree, options: EntityCreateGeneratorSchema): Promise<void>;
4
+ //# sourceMappingURL=generator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../src/generators/entity-create/generator.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,IAAI,EACV,MAAM,YAAY,CAAC;AAIpB,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAE/D,wBAA8B,qBAAqB,CACjD,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,2BAA2B,iBAuBrC"}
@@ -0,0 +1,70 @@
1
+ import { joinPathFragments, readProjectConfiguration, } from '@nx/devkit';
2
+ import { isAbsolute, posix } from 'node:path';
3
+ import createEntity from '../../executors/entity-create/executor.js';
4
+ import { normalizeName } from '../../utils/shared.js';
5
+ export default async function entityCreateGenerator(tree, options) {
6
+ const projectName = requireOption(options.project, 'project');
7
+ const entityName = normalizeName(requireOption(options.name, 'name'));
8
+ const projectConfig = readProjectConfiguration(tree, projectName);
9
+ const targetDirectory = resolveTargetDirectory(projectConfig.projectType, options.directory);
10
+ const context = createExecutorContext(tree, projectName);
11
+ const result = await createEntity({
12
+ projectRoot: projectConfig.root,
13
+ path: joinPathFragments(targetDirectory, entityName),
14
+ args: options.args,
15
+ }, context);
16
+ if (!result.success) {
17
+ throw new Error('TypeORM entity:create failed.');
18
+ }
19
+ }
20
+ function resolveTargetDirectory(projectType, directory) {
21
+ if (!directory) {
22
+ return projectType === 'application'
23
+ ? 'src/entities'
24
+ : 'src/infrastructure-persistence/entities';
25
+ }
26
+ return normalizeRelativeDirectory(directory);
27
+ }
28
+ function normalizeRelativeDirectory(directory) {
29
+ const trimmedDirectory = directory.trim();
30
+ if (trimmedDirectory.length === 0) {
31
+ throw new Error('Provide a non-empty directory when using the directory option.');
32
+ }
33
+ if (isAbsolute(trimmedDirectory)) {
34
+ throw new Error('The directory option must be relative to the project root.');
35
+ }
36
+ const normalizedDirectory = posix
37
+ .normalize(trimmedDirectory.replace(/\\/g, '/').replace(/^\.\//, ''))
38
+ .replace(/^\.\//, '');
39
+ if (normalizedDirectory.length === 0 ||
40
+ normalizedDirectory === '.' ||
41
+ normalizedDirectory === '..' ||
42
+ normalizedDirectory.startsWith('../')) {
43
+ throw new Error('The directory option must stay within the project root.');
44
+ }
45
+ return normalizedDirectory;
46
+ }
47
+ function requireOption(value, optionName) {
48
+ const trimmed = value?.trim();
49
+ if (!trimmed) {
50
+ throw new Error(`Provide a value for the ${optionName} option.`);
51
+ }
52
+ return trimmed;
53
+ }
54
+ function createExecutorContext(tree, projectName) {
55
+ const projectConfig = readProjectConfiguration(tree, projectName);
56
+ return {
57
+ root: tree.root,
58
+ projectName,
59
+ projectsConfigurations: {
60
+ version: 2,
61
+ projects: {
62
+ [projectName]: {
63
+ root: projectConfig.root,
64
+ projectType: projectConfig.projectType,
65
+ targets: projectConfig.targets ?? {},
66
+ },
67
+ },
68
+ },
69
+ };
70
+ }
@@ -0,0 +1,28 @@
1
+ {
2
+ "$schema": "http://json-schema.org/schema",
3
+ "title": "TypeORM Entity Create Generator",
4
+ "type": "object",
5
+ "properties": {
6
+ "project": {
7
+ "type": "string",
8
+ "description": "Name of the existing Nx project to scaffold an entity for."
9
+ },
10
+ "name": {
11
+ "type": "string",
12
+ "description": "Entity name. Spaces are normalized to hyphens."
13
+ },
14
+ "directory": {
15
+ "type": "string",
16
+ "description": "Optional directory relative to the project root where the entity should be created."
17
+ },
18
+ "args": {
19
+ "type": "array",
20
+ "items": {
21
+ "type": "string"
22
+ },
23
+ "description": "Additional CLI arguments passed through to TypeORM."
24
+ }
25
+ },
26
+ "required": ["project", "name"],
27
+ "additionalProperties": false
28
+ }
@@ -0,0 +1,4 @@
1
+ import { type Tree } from '@nx/devkit';
2
+ import type { MigrationApiGeneratorSchema } from './schema.js';
3
+ export default function migrationApiGenerator(tree: Tree, options: MigrationApiGeneratorSchema): Promise<void>;
4
+ //# sourceMappingURL=generator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../src/generators/migration-api/generator.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,IAAI,EACV,MAAM,YAAY,CAAC;AAkBpB,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAwM/D,wBAA8B,qBAAqB,CACjD,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,2BAA2B,iBA2IrC"}