Implementation using metaprogramming

Metaprogramming in ORMs: Code generation on the fly

Metaprogramming is a programming technique that allows programs to create or modify other programs or even themselves during execution. In the context of my ORM system, metaprogramming is crucial for enabling dynamic code generation specific to the database type and for providing flexibility in defining and configuring decorators used to interact with the database.

What is Metaprogramming? Metaprogramming allows the creation of programs that can analyze, modify, or generate other code. This can include:

  • Code Analysis: Checking and modifying existing codebases.

  • Code Generation: Creating new code snippets during program execution.

  • Code Modification: Changing existing code constructs on the fly.

Principles of Metaprogramming in My ORM System

  1. Dynamic Interface Generation: In my system, TypeScript interfaces for decorator parameters are dynamically generated based on the database type. This ensures accuracy and correctness of parameters that can be used when interacting with the database.

  2. Polymorphism: Metaprogramming provides polymorphism in my decorators, allowing the same decorator to support different parameters for different databases. For example, the parameters for the Index decorator differ for PostgreSQL and MySQL.

  3. Reflection: The use of the reflect-metadata library to collect and store metadata about decorators. This allows dynamic modification of code behavior based on information stored during program execution.

Implementation of Metaprogramming Here’s how metaprogramming is implemented in my ORM system:

  1. Index Decorator: The Index decorator is used to add metadata about indexes to a table. It writes this metadata to reflection, allowing it to be processed dynamically later.

import 'reflect-metadata';
import { IndexDecoratorInterface, IndexMetadataInterface } from '@decorators/index/interfaces';
import { constants } from '@core/constants';

export function Index({ tableName, indexName, columns, options }: IndexDecoratorInterface) {
  return function(constructor: Function) {
    if (!tableName) {
      console.info(
        'Ви вказали назву таблиці не коректно або вона відсутня, тому назва буде взята за назвою класу'
      );
      tableName = constructor.name;
    }
    let indexes: IndexMetadataInterface[] = Reflect.getMetadata(constants.decoratorsMetadata.indexes, constructor.prototype) || [];

    indexes.push({ tableName, indexName, columns, options });

    Reflect.defineMetadata(constants.decoratorsMetadata.indexes, indexes, constructor.prototype);
  };
}

  1. Generating Interfaces for Decorator Parameters:

Using the FileStructureManager class and TypescriptCodeGenerator, interfaces for decorator parameters are generated based on the database type. This ensures that users can only use correct parameters specific to the database they are working with.

import { DatabasesTypes } from '@core/enums';
import {
  OptionsToCreateFieldInterface,
  TypescriptCodeGenerator,
  TypescriptCodeGeneratorInterface
} from '@utils/typescript-code-generator';
import { ConnectionData } from '@core/types';

export class FileStructureManager {
  private static readonly _configFilePath = path.join(__dirname, '../../../..', '/tsconfig.json');
  private static _typescriptCodeGenerator: TypescriptCodeGeneratorInterface =
    new TypescriptCodeGenerator(this._configFilePath);

  static manage(connectionData: ConnectionData) {
    this._generateIndexOptionsDecoratorInterface(connectionData);
    // Інші методи для генерації інтерфейсів
  }

  private static _generateIndexOptionsDecoratorInterface(connectionData: ConnectionData) {
    const fileName = 'index-options-decorator.interface.d.ts';
    const filePath = path.join(__dirname, '../..', '/decorators/index/interfaces', fileName);

    const interfaceFields: OptionsToCreateFieldInterface[] = [
      {
        fieldName: 'isUnique',
        isFieldOptional: true,
        fieldType: { type: 'boolean' }
      },
      {
        fieldName: 'included',
        isFieldOptional: true,
        fieldType: { type: 'string', isArray: true }
      }
    ];

    if (connectionData.type === DatabasesTypes.POSTGRES) {
      interfaceFields.push(
        {
          fieldName: 'isHash',
          isFieldOptional: true,
          fieldType: { type: 'boolean' }
        },
        {
          fieldName: 'isGist',
          isFieldOptional: true,
          fieldType: { type: 'boolean' }
        }
        // Інші параметри для PostgreSQL
      );
    }

    if (connectionData.type === DatabasesTypes.MYSQL) {
      interfaceFields.push(
        {
          fieldName: 'isFulltext',
          isFieldOptional: true,
          fieldType: { type: 'boolean' }
        },
        {
          fieldName: 'isSpatial',
          isFieldOptional: true,
          fieldType: { type: 'boolean' }
        }
        // Інші параметри для MySQL
      );
    }

    this._typescriptCodeGenerator.generateInterfaceFile(
      fileName,
      filePath,
      'IndexOptionsDecoratorInterface',
      interfaceFields
    );
  }
}

  1. Generating TypeScript Files:

Detailed description of how TypescriptCodeGenerator works

The TypescriptCodeGenerator class is responsible for generating TypeScript files, such as interfaces and types, needed for the proper functioning of your ORM system. It uses the TypeScript API to create and write new files. Here’s a detailed overview of its operations:

Main Functions of TypescriptCodeGenerator

  1. Interface File Generation: The class generates TypeScript interfaces for decorators and parameters based on provided data. These interfaces are used for type-checking parameters and settings in your ORM system.

  2. TypeScript Code Formation: Using the TypeScript API, the class forms and generates code for interfaces, which is then written to files.

  3. Import Handling: Generates imports for types used in interfaces, ensuring proper syntax for dependencies.

Key Methods of TypescriptCodeGenerator

  1. generateInterfaceFile:

    • Purpose: Generates a TypeScript file with an interface.

    • Parameters:

      • interfaceFileName: The name of the file to be created.

      • interfaceFilePath: The path to the file.

      • interfaceName: The name of the interface.

      • interfaceFields: Fields of the interface.

      • interfaceImports: Imports to add to the file.

    • Process:

      • Deletes the existing file if present.

      • Generates new TypeScript code for the interface, including imports.

      • Writes the generated code to the file.

generateInterfaceFile(
  interfaceFileName: string,
  interfaceFilePath: string,
  interfaceName: string,
  interfaceFields: OptionsToCreateFieldInterface[],
  interfaceImports?: ts.ImportDeclaration[]
): void {
  FS.deleteFile(interfaceFilePath); // Видаляє старий файл
  IncrementalTypeIndexator.performIncrementalTypeIndexing(this._configFilePath); // Оновлює індексацію

  fs.writeFileSync(
    interfaceFilePath,
    this.generateInterface(
      interfaceFileName,
      this.formInterface(
        interfaceName,
        interfaceFields
      ),
      interfaceImports
    ),
    'utf8'
  );
}

  1. generateInterface:

    • Purpose: Generates TypeScript code for an interface.

    • Parameters:

      • fileName: The file name.

      • interfaceDeclaration: The interface declaration.

      • imports: Imports for the file.

    • Process:

      • Creates a new SourceFile with imports and interface declaration.

      • Uses Printer to convert the TypeScript structure to a text format.

generateInterface(
  fileName: string,
  interfaceDeclaration?: ts.InterfaceDeclaration,
  imports?: ts.ImportDeclaration[]
): string {
  const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
  const resultFile = ts.createSourceFile(fileName, '', ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);

  const resultWithImports = ts.factory.updateSourceFile(resultFile, imports || []);
  const resultWithInterface = ts.factory.updateSourceFile(resultWithImports, resultWithImports.statements.concat([interfaceDeclaration]));

  return printer.printFile(resultWithInterface);
}

  1. formImport:

    • Purpose: Forms an import for a TypeScript file.

    • Parameters:

      • importName: The import name.

      • importPath: The module path.

    • Process:

      • Creates an import for the specified type with the appropriate path.

formImport(importName: string, importPath: string): [ts.ImportDeclaration, ts.TypeReferenceNode] {
  const formedImport = ts.factory.createImportDeclaration(
    undefined,
    ts.factory.createImportClause(
      undefined,
      undefined,
      ts.factory.createNamedImports([
        ts.factory.createImportSpecifier(undefined, ts.factory.createIdentifier(importName), ts.factory.createIdentifier(importName))
      ])
    ),
    ts.factory.createStringLiteral(importPath),
    undefined
  );
  const typeNode = ts.factory.createTypeReferenceNode(importName, []);

  return [formedImport, typeNode];
}

  1. formInterface:

    • Purpose: Forms the interface declaration.

    • Parameters:

      • interfaceName: The name of the interface.

      • fields: The fields of the interface.

    • Process:

      • Creates a new InterfaceDeclaration with specified fields and possible imports.

formInterface(interfaceName: string, fields: OptionsToCreateFieldInterface[]): ts.InterfaceDeclaration {
  const interfaceDeclaration = ts.factory.createInterfaceDeclaration(
    undefined,
    interfaceName,
    [],
    undefined,
    fields.map(this.formField)
  );

  return ts.factory.updateInterfaceDeclaration(
    interfaceDeclaration,
    [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
    interfaceDeclaration.name,
    interfaceDeclaration.typeParameters,
    interfaceDeclaration.heritageClauses,
    interfaceDeclaration.members
  );
}

  1. formField:

    • Purpose: Forms a field for the interface.

    • Parameters:

      • field: Description of the field.

    • Process:

      • Creates a PropertySignature for a field with the appropriate type and possible parameters.

formField = ({ isFieldOptional, fieldName, fieldType }: OptionsToCreateFieldInterface): ts.PropertySignature => {
  const typeArray = Array.isArray(fieldType) ? fieldType : [fieldType];
  const dataType = typeArray.map((type) =>
    'type' in type && type.type ? this.handleTypeElement(type) : type as ts.TypeReferenceNode
  );
  const dataTypeNode = dataType.length === 1
    ? dataType[0]
    : ts.factory.createUnionTypeNode(dataType);

  return ts.factory.createPropertySignature(
    undefined,
    fieldName,
    isFieldOptional ? ts.factory.createToken(ts.SyntaxKind.QuestionToken) : undefined,
    dataTypeNode
  );
};

  1. handleTypeElement:

    • Purpose: Handles the element type for interface fields.

    • Parameters:

      • typeElement: Element type.

    • Process:

      • Sets the type for the field depending on whether it is a simple type, an array, or a literal.

handleTypeElement(typeElement: FieldTypeInterface): ts.TypeNode {
  let elementType: ts.TypeNode = typeElement.isStringLiteral ?
    ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral(typeElement.type)) :
    ts.factory.createTypeReferenceNode(typeElement.type, []);

  return typeElement.isArray && !typeElement.isStringLiteral
    ? ts.factory.createArrayTypeNode(elementType)
    : elementType;
};

Advantages of Metaprogramming in the Context of My ORM

  1. Flexibility and Scalability: Dynamic generation of interfaces allows for easy adaptation to new database versions or changes in requirements, without the need to manually update code for each database individually.

  2. Increased Accuracy: Generated interfaces ensure that users have access to the correct parameters for a specific database, reducing the likelihood of errors when configuring decorators.

  3. Automation: Automatic updating of interfaces reduces the need for manual code changes, making the process more efficient and less prone to errors.

Metaprogramming is a crucial aspect of my ORM system as it provides flexibility and accuracy when working with different types of databases, which is key to ensuring correct operation and effective data management.

PreviousImplementation using genericsNextDecorators

Last updated