angel-manager v1.0.1

Angel Manager é um gerenciador de arquitetura baseado em templates via CLI para Node.js. Totalmente customizável e independente de framework, esta ferramenta facilita a implementação e manutenção de arquiteturas de software web, automatizando a geração de código e padronizando convenções tanto no frontend quanto no backend. Ideal para desenvolvedores que buscam modularizar e otimizar seu fluxo de trabalho em Node.js a partir de modelagem e geração de código.

Índice

• Índice
• Instalação
• Configuração
• Uso
• Reutilização
• Diretório scaffolding
• Criando um novo módulo
• Construindo um Template
  • Exemplo de Template
• Construção do Design-Time Input
  • Tabela de Tipos
  • Método run
    • Método renderTemplate
    • Método includeRelated
• angel-managerrc.json
• Contribuições

Instalação

Instale o Angel Manager como uma dependência de desenvolvimento no seu projeto:

npm install angel-manager --save-dev

ou

yarn add -D angel-manager

Configuração

Após a instalação, a utilização da CLI (Linha de Comando) estará disponível através de npx angel. Inicie a estrutura básica para configuração do Angel Manager:

npx angel init

Este comando criará a estrutura de diretórios necessária dentro do diretório src/scaffolding, que inclui os subdiretórios architecture e commands para definir templates e comandos customizados.

Uso

Para listar todos os comandos disponíveis, use:

npx angel -h

Reutilização

Se você já criou um modelo de arquitetura em outro projeto, pode reutilizá-lo facilmente. Para isso, copie o diretório scaffolding do projeto anterior e cole-o no novo projeto.

Em seguida, utilize o comando:

npx angel apply

Esse comando aplica a estrutura de diretórios modelada em scaffolding/architecture, inicializando automaticamente os diretórios no novo projeto. Dessa forma, você evita configurar manualmente a arquitetura para cada projeto.

Por exemplo, a estrutura modelada:

scaffolding/
└── architecture/
    ├── components/
    └── views/
        ├── admin/
        └── public/

Deve gerar:

src/
└── components/
└── views/
    ├── admin/
    └── public/

Diretório scaffolding

O diretório scaffolding é onde se define o modelo da arquitetura do projeto. Ele contém dois subdiretórios principais:

• /architecture: Este subdiretório armazena os templates que representam a estrutura modular da arquitetura. Deve refletir a organização de diretórios desejada para o projeto. Cada módulo (como components ou views) terá seu próprio template.
• /commands: Contém arquivos TypeScript que configuram as transformações dos templates. Cada modelo na arquitetura deve ter um arquivo correspondente em commands para definir as regras de geração e transformação de código. Esses arquivos também servem para mapear os comandos disponíveis na CLI, permitindo que o Angel Manager identifique e execute comandos de geração para cada template.

Por exemplo:

src/
└── scaffolding/
    ├── architecture/  # Armazena templates de arquitetura, como components, views, etc.
    │   ├── components/
    │   └── views/
    │       ├── admin/
    │       └── public/
    │   └── ...    # Outros módulos da arquitetura...
    └── commands/  # Define regras de geração e mapeia comandos para cada modelo
        ├── Components.ts
        ├── AdminViews.ts
        └── PublicViews.ts

Criando um novo módulo

Ao criar um novo módulo, comece construindo o template e armazene-o no diretório correspondente dentro de scaffolding/architecture.

Em seguida, crie um novo arquivo no diretório commands, correspondente ao módulo que está sendo modelado. Para isso, o Angel Manager fornece um comando para inicializar a estrutura base do arquivo .ts, recebendo como argumento o nome do módulo:

npx angel create:command <commandName>

Construindo um Template

O Angel Manager utiliza a Liquid Engine para processar os templates criados. Para entender melhor como construir seus templates, consulte a documentação da engine em Liquid Engine.

Como exemplo, vamos construir o template para o módulo components em um projeto que utiliza React.

Exemplo de Template

import './{{ pascal.componentName }}.css';

interface {{ pascal.componentName }}Props {
  /* As propriedades do componente */
  requiredProp: string;
  optionalProp?: string;
}

function {{ pascal.componentName }}({
  requiredProp,
  optionalProp = 'Valor Padrão',
}: {{ pascal.componentName }}Props): JSX.Element {
  return (
    <div className="{{ kebab.componentName }}">
      Seu HTML aqui: {requiredProp}, {optionalProp}
    </div>
  );
}

export default {{ pascal.componentName }};

/**
 * @note
 * Não se esqueça de listar este novo componente.
 * Adicione o seguinte trecho em components/index.ts:
 * export { default as {{ pascal.componentName }} } from './{{ pascal.componentName }}/{{ pascal.componentName }}';
 */

Importante!!!!: Este é apenas um exemplo de template. Ele é totalmente customizável para se ajustar às suas necessidades. A engine de templates não depende de uma linguagem de saída específica. A extensão e o nome do arquivo gerado são definidos no arquivo TypeScript correspondente em commands.

Construção do Design-Time Input

Ao arquivo de configuração do modelo, definido dentro de /commands chamamos design-time input. Durante a construção deste, os desenvolvedores podem personalizar a geração de código de acordo com as necessidades do projeto.

O exemplo a seguir mostra a implementação de um comando que gera um novo componente:

import {
  BaseCommand,
  FileConfig,
  Arg,
  RunnableArgs,
  renderTemplate,
} from 'angel-manager';

export default class Components extends BaseCommand {
  /**
   * O nome do comando, que será utilizado para executá-lo
   */
  public commandName = 'make:component';

  /**
   * Descrição do comando
   */
  public description = 'Cria um novo componente';

  /**
   * Caminho do template Liquid, relativo a scaffolding/architecture
   */
  public templatePath = 'components';

  /**
   * Caminho de destino para o arquivo gerado, relativo a src
   */
  public destinationPath = 'components';

  public file: FileConfig = {
    // Define nome do arquivo gerado
    name: { argName: 'componentName', case: 'camel' },
    // A extensão do arquivo gerado
    extension: 'tsx',
    // Se verdadeiro, o código será gerado dentro de um diretório nomeado conforme o arquivo
    subDir: true,
  };

  /**
   *
   * @returns um array de argumentos representando os parâmetros
   * que serão solicitados pela linha de comando e disponibilizados no template
   */
  public args(): Arg[] {
    return [{ name: 'componentName', type: 'string' }];
  }

  public async run(args: RunnableArgs): Promise<void> {
    try {
      await renderTemplate(this, args);
      includeRelated(this, args, ['css']);
    } catch (error) {
      console.error(error);
    }
  }
}

Tabela de Tipos

Método run

O método run é um método abstrato e assíncrono que executa a lógica do comando. Ele disponibiliza como argumento args, que são os parâmetros passados pelo usuário ao executar o comando. Dentro do método, o desenvolvedor tem a liberdade de definir a lógica de execução do comando da maneira que for necessária para o seu caso de uso.

No exemplo fornecido, a principal responsabilidade do método run é chamar a função renderTemplate e passar a si mesmo (this) e os argumentos (args) como parâmetros. A função renderTemplate, disponibilizada pelo Angel Manager será responsável por processar o template Liquid, substituindo os placeholders pelas variáveis definidas nos argumentos, e gerar o código de saída. O método run também inclui um bloco try-catch para capturar e tratar erros que possam ocorrer durante o processo de execução.

Método renderTemplate

O método assíncrono renderTemplate, disponibilizado pelo Angel Manager, é responsável por processar o template através da engine, utilizando os argumentos recebidos e os atributos estáticos. Ele gera o código de saída com base no template Liquid e nas configurações definidas.

Método includeRelated

O método síncrono includeRelated, disponibilizado pelo Angel Manager, permite a inclusão de arquivos vazios relacionados ao código gerado. Este método é útil quando é necessário criar arquivos complementares, como arquivos de estilo ou testes, no mesmo diretório do código gerado.

angel-managerrc.json

Este é o arquivo de configuração global do Angel Manager. Ele é utilizado para definir valores iniciais (default) para a construção dos modelos.

{
  "staticAttributes": {
    "extension": {
      "defaultValue": "tsx"
    },
    "subDir": {
      "defaultValue": true
    }
  }
}

Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues, enviar pull requests ou sugerir melhorias para a documentação.