@mutates/core - Mutates Docs

@mutates/core is the foundation package of the Mutates toolset that provides essential functionality for manipulating TypeScript Abstract Syntax Trees (AST). This package serves as the backbone for other specialized packages in the Mutates ecosystem.

Installation

Install @mutates/core using npm:

npm install @mutates/core

Core Concepts

The core package provides several key functionalities for AST manipulation:

Project Management

import { createProject, resetActiveProject, saveProject } from '@mutates/core';

// Create a new project
createProject();

// Make modifications...

// Save changes
saveProject();

// Reset the project state
resetActiveProject();

Source File Operations

import { createSourceFile } from '@mutates/core';

// Create a new TypeScript file
createSourceFile(
  'example.ts',
  `
  export class Example {
    greeting: string = 'Hello World';
  }
`,
);

Main Features

Class Manipulation

import { addClasses, editClasses, getClasses, removeClasses } from '@mutates/core';

// Add a new class
addClasses('path/to/file.ts', {
  name: 'MyClass',
  isExported: true,
  methods: [
    {
      name: 'myMethod',
      statements: 'return true;',
    },
  ],
});

// Get existing classes
const classes = getClasses({ pattern: 'path/to/file.ts' });

// Edit classes
editClasses(classes, () => ({
  isExported: true,
  name: 'UpdatedClassName',
}));

// Remove classes
removeClasses(classes);

Function Operations

import { addFunctions, editFunctions, getFunctions, removeFunctions } from '@mutates/core';

// Add a new function
addFunctions('path/to/file.ts', {
  name: 'myFunction',
  isExported: true,
  statements: 'return "Hello World";',
});

// Get existing functions
const functions = getFunctions({ pattern: 'path/to/file.ts' });

// Edit functions
editFunctions(functions, () => ({
  isAsync: true,
  statements: 'return Promise.resolve("Hello");',
}));

// Remove functions
removeFunctions(functions);

Property Management

import { addProperties, editProperties, getProperties, removeProperties } from '@mutates/core';

// Add class properties
addProperties(targetClass, {
  name: 'myProperty',
  type: 'string',
  initializer: '"default value"',
});

Method Operations

import { addMethods, editMethods, getMethods, removeMethods } from '@mutates/core';

// Add class methods
addMethods(targetClass, {
  name: 'myMethod',
  parameters: [
    {
      name: 'param',
      type: 'string',
    },
  ],
  statements: 'console.log(param);',
});

Decorator Management

import { addDecorators } from '@mutates/core';

// Add decorators
addDecorators(target, {
  name: 'MyDecorator',
  arguments: ['arg1', 'arg2'],
});

Working with Arrays

The package provides utilities for array manipulation:

import { arrayIncludes, pushToArray, removeFromArray } from '@mutates/core';

// Add elements to array
pushToArray(arrayExpression, 'newItem');

// Remove elements
removeFromArray(arrayExpression, 'itemToRemove');

// Check if array includes element
const hasItem = arrayIncludes(arrayExpression, 'searchItem');

Best Practices

Always create a project before making modifications:

createProject();

Save changes after modifications:

saveProject();

Clean up by resetting the project when done:

resetActiveProject();

Use pattern matching to target specific files:

getClasses({ pattern: 'src/**/*.ts' });

Error Handling

The package throws descriptive errors when operations fail. It's recommended to wrap operations in try-catch blocks:

try {
  createProject();
  // ... operations
  saveProject();
} catch (error) {
  console.error('Failed to modify source code:', error);
} finally {
  resetActiveProject();
}

Integration with Other Tools

@mutates/core is designed to work seamlessly with other packages in the Mutates ecosystem:

@mutates/angular for Angular-specific transformations
@mutates/nx for Nx workspace operations

Additional Resources

For more examples and detailed API documentation, visit the official documentation.