Generators & Code Generation

/**
 * Format all files in the tree using Prettier
 * @param tree - Virtual file system tree
 * @returns Promise that resolves when formatting is complete
 */
function formatFiles(tree: Tree): Promise<void>;

/**
 * Generate files from templates with variable substitution
 * @param tree - Virtual file system tree to write to
 * @param srcFolder - Source folder containing template files
 * @param target - Target directory for generated files
 * @param substitutions - Variables for template substitution
 * @param options - Optional generation options
 */
function generateFiles(
  tree: Tree,
  srcFolder: string,
  target: string,
  substitutions: Record<string, any>,
  options?: GenerateFilesOptions
): void;

/**
 * Convert TypeScript files to JavaScript
 * @param tree - Virtual file system tree
 * @param options - Conversion options
 */
function toJS(tree: Tree, options?: ToJSOptions): void;

/**
 * Update TypeScript configurations for JavaScript compilation
 * @param tree - Virtual file system tree
 * @param options - Update options
 */
function updateTsConfigsToJs(tree: Tree, options?: { projectRoot: string }): void;

/**
 * Execute generator callbacks in sequence
 * @param callbacks - Array of generator callbacks to execute
 * @returns Promise that resolves when all callbacks complete
 */
function runTasksInSerial(...callbacks: GeneratorCallback[]): Promise<void>;

import { 
  Tree, 
  generateFiles, 
  formatFiles, 
  names 
} from "@nrwl/devkit";
import * as path from "path";

export default async function myGenerator(tree: Tree, schema: any) {
  // Generate files from templates
  generateFiles(
    tree,
    path.join(__dirname, 'files'), // Template directory
    schema.projectRoot,
    {
      ...schema,
      ...names(schema.name),
      template: '' // Remove .template suffix from file names
    }
  );
  
  // Format all generated files
  await formatFiles(tree);
}

/**
 * Generator function signature
 * @template T - Schema type for generator options
 */
type Generator<T = any> = (
  tree: Tree,
  schema: T
) => void | GeneratorCallback | Promise<void | GeneratorCallback>;

/**
 * Callback function executed after filesystem changes are applied
 */
type GeneratorCallback = () => void | Promise<void>;

/**
 * Configuration for generators.json files
 */
interface GeneratorsJson {
  extends?: string;
  schematics?: Record<string, GeneratorConfiguration>;
  generators?: Record<string, GeneratorConfiguration>;
}

/**
 * Configuration for a single generator
 */
interface GeneratorConfiguration {
  factory: string;
  schema: string;
  aliases?: string[];
  hidden?: boolean;
  description?: string;
}

/**
 * Strategy for handling existing files during generation
 */
enum OverwriteStrategy {
  /**
   * Throw an error if file exists
   */
  ThrowIfExisting = 'ThrowIfExisting',
  /**
   * Overwrite existing files
   */
  Overwrite = 'Overwrite',
  /**
   * Skip files that already exist
   */
  SkipIfExisting = 'SkipIfExisting'
}

/**
 * Options for file generation
 */
interface GenerateFilesOptions {
  /** Strategy for handling existing files */
  overwriteStrategy?: OverwriteStrategy;
}

/**
 * Options for TypeScript to JavaScript conversion
 */
interface ToJSOptions {
  extension?: '.js' | '.mjs' | '.cjs';
  errors?: 'warn' | 'ignore';
}

import { Tree, Generator, GeneratorCallback } from "@nrwl/devkit";

interface Schema {
  name: string;
  directory?: string;
  skipTests?: boolean;
}

const myGenerator: Generator<Schema> = async (tree: Tree, options: Schema) => {
  // Generate files
  generateFiles(tree, __dirname + '/files', options.directory || '.', options);
  
  // Return a callback for post-generation tasks
  const callback: GeneratorCallback = async () => {
    console.log('Generator completed successfully!');
  };
  
  return callback;
};

export default myGenerator;

/**
 * Generate files from templates with advanced options
 * @param tree - Virtual file system tree
 * @param srcFolder - Template source directory
 * @param target - Target output directory
 * @param substitutions - Template variables and options
 */
function generateFiles(
  tree: Tree,
  srcFolder: string,
  target: string,
  substitutions: Record<string, any> & {
    template?: string;
    dot?: string;
    tmpl?: string;
  }
): void;

// files/src/lib/__name__.ts.template
export class <%= className %> {
  constructor(private config: <%= className %>Config) {}
  
  <% if (includeAsyncMethods) { %>
  async initialize(): Promise<void> {
    // Async initialization logic
  }
  <% } %>
}

// Generator usage
generateFiles(tree, path.join(__dirname, 'files'), projectRoot, {
  ...options,
  ...names(options.name),
  template: '', // Removes .template extension
  dot: '.', // Converts __dot__ to .
  includeAsyncMethods: options.async
});

/**
 * Generate various name formats from a base name
 * @param name - Base name to transform
 * @returns Object with different name formats
 */
function names(name: string): {
  /** Original name as provided */
  name: string;
  /** PascalCase class name */
  className: string;
  /** camelCase property name */
  propertyName: string;
  /** CONSTANT_CASE name */
  constantName: string;
  /** kebab-case file name */
  fileName: string;
};

import { names } from "@nrwl/devkit";

const nameFormats = names('my-awesome-feature');
console.log(nameFormats);
// Output:
// {
//   name: 'my-awesome-feature',
//   className: 'MyAwesomeFeature',
//   propertyName: 'myAwesomeFeature',
//   constantName: 'MY_AWESOME_FEATURE',
//   fileName: 'my-awesome-feature'
// }

/**
 * Convert Nx generator to Angular schematic format
 * @param generator - Nx generator function
 * @returns Angular schematic factory function
 */
function convertNxGenerator<T = any>(generator: Generator<T>): any;

/**
 * Convert Nx executor to Angular builder format
 * @param executor - Nx executor function
 * @returns Angular builder function
 */
function convertNxExecutor<T = any>(executor: Executor<T>): any;

import { convertNxGenerator, Generator } from "@nrwl/devkit";

const myGenerator: Generator = (tree, options) => {
  // Generator implementation
};

// Convert for use with Angular CLI
export const schematic = convertNxGenerator(myGenerator);