0
# Utility Functions
1

2
NgRx Schematics core utilities that provide shared functionality for AST manipulation, project analysis, string transformations, and code generation support. These utilities are used internally by all schematics and can be imported for custom schematic development.
3

4
## Capabilities
5

6
### String Utilities
7

8
String manipulation functions following Angular and NgRx naming conventions.
9

10
```typescript { .api }
11
/**
12
 * String utility functions for name transformations
13
 */
14
interface StringUtils {
15
  /** Convert string to dash-case (kebab-case) */
16
  dasherize: (str: string) => string;
17
  /** Convert string from camelCase to words */
18
  decamelize: (str: string) => string;
19
  /** Convert string to camelCase */
20
  camelize: (str: string) => string;
21
  /** Convert string to PascalCase (UpperCamelCase) */
22
  classify: (str: string) => string;
23
  /** Convert string to snake_case */
24
  underscore: (str: string) => string;
25
  /** Group strings with separators */
26
  group: (str: string, groupName?: string) => string;
27
  /** Capitalize first letter */
28
  capitalize: (str: string) => string;
29
  /** Generate feature path from name */
30
  featurePath: (name: string) => string;
31
  /** Convert string to plural form */
32
  pluralize: (str: string) => string;
33
}
34

35
// Access to string utilities
36
import { stringUtils } from '@ngrx/schematics/schematics-core';
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import { stringUtils } from '@ngrx/schematics/schematics-core';
43

44
// String transformations
45
stringUtils.dasherize('UserProfile');     // 'user-profile'
46
stringUtils.camelize('user-profile');     // 'userProfile'
47
stringUtils.classify('user-profile');     // 'UserProfile'
48
stringUtils.underscore('userProfile');    // 'user_profile'
49
stringUtils.capitalize('user');           // 'User'
50
stringUtils.pluralize('user');            // 'users'
51

52
// Feature path generation
53
stringUtils.featurePath('user');          // 'user'
54
stringUtils.group('actions', 'user');     // 'user/actions'
55
```
56

57
### AST Manipulation Functions
58

59
TypeScript Abstract Syntax Tree manipulation utilities for code generation and modification.
60

61
```typescript { .api }
62
/**
63
 * Find AST nodes matching specific criteria
64
 * @param node - Source AST node to search
65
 * @param kind - TypeScript syntax kind to find
66
 * @param max - Maximum number of results
67
 * @returns Array of matching nodes
68
 */
69
function findNodes(
70
  node: ts.Node,
71
  kind: ts.SyntaxKind,
72
  max?: number
73
): ts.Node[];
74

75
/**
76
 * Get all source nodes from a TypeScript source file
77
 * @param sourceFile - TypeScript source file
78
 * @returns Array of source nodes
79
 */
80
function getSourceNodes(sourceFile: ts.SourceFile): ts.Node[];
81

82
/**
83
 * Get decorator metadata from a class or property
84
 * @param source - TypeScript source file
85
 * @param identifier - Decorator name to find
86
 * @returns Decorator metadata nodes
87
 */
88
function getDecoratorMetadata(
89
  source: ts.SourceFile,
90
  identifier: string
91
): ts.Node[];
92

93
/**
94
 * Get content of a key literal in an object
95
 * @param source - TypeScript source file
96
 * @param literal - Key name to find
97
 * @returns Content of the key literal
98
 */
99
function getContentOfKeyLiteral(
100
  source: ts.SourceFile,
101
  literal: string
102
): string | null;
103
```
104

105
### Import Management
106

107
Functions for managing TypeScript imports and module dependencies.
108

109
```typescript { .api }
110
/**
111
 * Insert an import statement into a TypeScript file
112
 * @param source - TypeScript source file
113
 * @param fileToEdit - Path of file being edited
114
 * @param symbolName - Symbol to import
115
 * @param fileName - Module to import from
116
 * @param isDefault - Whether this is a default import
117
 * @returns Change object representing the import insertion
118
 */
119
function insertImport(
120
  source: ts.SourceFile,
121
  fileToEdit: string,
122
  symbolName: string,
123
  fileName: string,
124
  isDefault?: boolean
125
): Change;
126

127
/**
128
 * Replace an existing import with a new one
129
 * @param source - TypeScript source file
130
 * @param path - File path
131
 * @param importFrom - Original import source
132
 * @param importAsIs - New import source
133
 * @returns Change object representing the import replacement
134
 */
135
function replaceImport(
136
  source: ts.SourceFile,
137
  path: string,
138
  importFrom: string,
139
  importAsIs: string
140
): Change;
141
```
142

143
**Usage Examples:**
144

145
```typescript
146
import { insertImport, replaceImport } from '@ngrx/schematics/schematics-core';
147
import * as ts from 'typescript';
148

149
// Insert new import
150
const change = insertImport(
151
  sourceFile,
152
  'src/app/user/user.component.ts',
153
  'Store',
154
  '@ngrx/store'
155
);
156

157
// Replace existing import
158
const replaceChange = replaceImport(
159
  sourceFile,
160
  'src/app/user/user.component.ts',
161
  './old-path',
162
  './new-path'
163
);
164
```
165

166
### Angular Module Utilities
167

168
Functions for modifying Angular modules with proper dependency injection and imports.
169

170
```typescript { .api }
171
/**
172
 * Add import to NgModule imports array
173
 * @param source - TypeScript source file
174
 * @param modulePath - Path to module file
175
 * @param importText - Import text to add
176
 * @param importPath - Path of import
177
 * @returns Array of changes to apply
178
 */
179
function addImportToModule(
180
  source: ts.SourceFile,
181
  modulePath: string,
182
  importText: string,
183
  importPath: string
184
): Change[];
185

186
/**
187
 * Add declaration to NgModule declarations array
188
 * @param source - TypeScript source file
189
 * @param modulePath - Path to module file
190
 * @param classifiedName - Name of component/directive/pipe
191
 * @param importPath - Path to import from
192
 * @returns Array of changes to apply
193
 */
194
function addDeclarationToModule(
195
  source: ts.SourceFile,
196
  modulePath: string,
197
  classifiedName: string,
198
  importPath: string
199
): Change[];
200

201
/**
202
 * Add export to NgModule exports array
203
 * @param source - TypeScript source file
204
 * @param modulePath - Path to module file
205
 * @param classifiedName - Name to export
206
 * @param importPath - Path to import from
207
 * @returns Array of changes to apply
208
 */
209
function addExportToModule(
210
  source: ts.SourceFile,
211
  modulePath: string,
212
  classifiedName: string,
213
  importPath: string
214
): Change[];
215

216
/**
217
 * Add provider to NgModule providers array
218
 * @param source - TypeScript source file
219
 * @param modulePath - Path to module file
220
 * @param classifiedName - Provider name
221
 * @param importPath - Path to import from
222
 * @returns Array of changes to apply
223
 */
224
function addProviderToModule(
225
  source: ts.SourceFile,
226
  modulePath: string,
227
  classifiedName: string,
228
  importPath: string
229
): Change[];
230
```
231

232
### Project Analysis Functions
233

234
Utilities for analyzing Angular workspace and project structure.
235

236
```typescript { .api }
237
/**
238
 * Get project path for file generation
239
 * @param host - Schematic tree host
240
 * @param options - Schematic options
241
 * @returns Resolved project path
242
 */
243
function getProjectPath(host: Tree, options: any): string;
244

245
/**
246
 * Get project configuration from angular.json
247
 * @param host - Schematic tree host
248
 * @param projectName - Name of project
249
 * @returns Project configuration object
250
 */
251
function getProject(host: Tree, projectName: string): any;
252

253
/**
254
 * Check if project is a library
255
 * @param host - Schematic tree host
256
 * @param options - Schematic options
257
 * @returns True if project is library
258
 */
259
function isLib(host: Tree, options: any): boolean;
260

261
/**
262
 * Find module file from schematic options
263
 * @param host - Schematic tree host
264
 * @param options - Schematic options with module path
265
 * @returns Path to module file
266
 */
267
function findModuleFromOptions(host: Tree, options: any): string;
268

269
/**
270
 * Find component file from schematic options
271
 * @param host - Schematic tree host
272
 * @param options - Schematic options
273
 * @returns Path to component file
274
 */
275
function findComponentFromOptions(host: Tree, options: any): string;
276
```
277

278
### Change Management
279

280
Classes and functions for managing code changes and transformations.
281

282
```typescript { .api }
283
/**
284
 * Base class for representing code changes
285
 */
286
abstract class Change {
287
  abstract apply(host: Host): Promise<void> | void;
288
  abstract readonly path: string | null;
289
  abstract readonly order: number;
290
  abstract readonly description: string;
291
}
292

293
/**
294
 * Represents an insertion change
295
 */
296
class InsertChange extends Change {
297
  constructor(public path: string, public pos: number, public toAdd: string);
298
  apply(host: Host): void;
299
}
300

301
/**
302
 * Represents a removal change
303
 */
304
class RemoveChange extends Change {
305
  constructor(public path: string, public pos: number, public length: number);
306
  apply(host: Host): void;
307
}
308

309
/**
310
 * Represents a replacement change
311
 */
312
class ReplaceChange extends Change {
313
  constructor(
314
    public path: string,
315
    public pos: number,
316
    public oldText: string,
317
    public newText: string
318
  );
319
  apply(host: Host): void;
320
}
321

322
/**
323
 * Create a change recorder for batch operations
324
 * @param host - Schematic tree host
325
 * @param path - File path
326
 * @returns Update recorder
327
 */
328
function createChangeRecorder(host: Tree, path: string): UpdateRecorder;
329

330
/**
331
 * Commit multiple changes to files
332
 * @param host - Schematic tree host
333
 * @param changes - Array of changes to apply
334
 */
335
function commitChanges(host: Tree, changes: Change[]): void;
336
```
337

338
### NgRx-Specific Utilities
339

340
Specialized utilities for NgRx pattern generation and state management.
341

342
```typescript { .api }
343
/**
344
 * Add reducer to state interface
345
 * @param source - TypeScript source file
346
 * @param reducerPath - Path to reducer file
347
 * @param reducerName - Name of reducer
348
 * @returns Change objects for state modification
349
 */
350
function addReducerToState(
351
  source: ts.SourceFile,
352
  reducerPath: string,
353
  reducerName: string
354
): Change[];
355

356
/**
357
 * Add reducer to ActionReducerMap
358
 * @param source - TypeScript source file
359
 * @param reducerPath - Path to reducer file
360
 * @param reducerName - Name of reducer
361
 * @param featureKey - Feature key for reducer
362
 * @returns Change objects for reducer map modification
363
 */
364
function addReducerToActionReducerMap(
365
  source: ts.SourceFile,
366
  reducerPath: string,
367
  reducerName: string,
368
  featureKey: string
369
): Change[];
370

371
/**
372
 * Get prefix for action types
373
 * @param options - Schematic options
374
 * @returns Formatted prefix string
375
 */
376
function getPrefix(options: any): string;
377

378
/**
379
 * Omit properties from object (utility for immutable updates)
380
 * @param obj - Source object
381
 * @param keys - Keys to omit
382
 * @returns New object without specified keys
383
 */
384
function omit<T, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
385
```
386

387
### Workspace Configuration
388

389
Functions for reading and modifying Angular workspace configuration.
390

391
```typescript { .api }
392
/**
393
 * Application configuration interface
394
 */
395
interface AppConfig {
396
  project: string;
397
  path: string;
398
  sourceRoot: string;
399
  prefix: string;
400
}
401

402
/**
403
 * Get workspace configuration from angular.json
404
 * @param host - Schematic tree host
405
 * @returns Workspace configuration object
406
 */
407
function getWorkspace(host: Tree): any;
408

409
/**
410
 * Get path to workspace configuration file
411
 * @param host - Schematic tree host
412
 * @returns Path to angular.json or workspace.json
413
 */
414
function getWorkspacePath(host: Tree): string;
415
```
416

417
### Name Parsing
418

419
Utilities for parsing file names and paths with proper Angular conventions.
420

421
```typescript { .api }
422
/**
423
 * Parse name and path from schematic options
424
 * @param path - Base path
425
 * @param name - Item name
426
 * @returns Parsed name and path information
427
 */
428
function parseName(path: string, name: string): {
429
  name: string;
430
  path: string;
431
};
432

433
/**
434
 * Build relative path between two files
435
 * @param from - Source file path
436
 * @param to - Target file path
437
 * @returns Relative path string
438
 */
439
function buildRelativePath(from: string, to: string): string;
440
```
441

442
### Package Management
443

444
Functions for managing package.json dependencies and configuration.
445

446
```typescript { .api }
447
/**
448
 * Add package to package.json dependencies
449
 * @param host - Schematic tree host
450
 * @param packageName - Package to add
451
 * @param version - Package version
452
 * @param dev - Whether to add to devDependencies
453
 * @returns Change objects for package.json modification
454
 */
455
function addPackageToPackageJson(
456
  host: Tree,
457
  packageName: string,
458
  version: string,
459
  dev?: boolean
460
): Change[];
461

462
/**
463
 * Update package version in package.json
464
 * @param host - Schematic tree host
465
 * @param packageName - Package to update
466
 * @param version - New version
467
 * @returns Change objects for package.json modification
468
 */
469
function updatePackage(
470
  host: Tree,
471
  packageName: string,
472
  version: string
473
): Change[];
474

475
/**
476
 * Get current platform version
477
 */
478
const platformVersion: string;
479
```