@chillapi/generator-tools

This package is used by any plugin that wants to generate a ChillAPI configuration.

Goals

Generate ChillAPI Config folder structure and operation descriptors

Available options:

• rootDirectory:string: the location where the ChillAPI configuration should be saved; default ./chillapi
• descriptorContent:function(op:OpenAPIOperation)=>string: a function that takes an OpenAPI operation and returns the content to be filled into the respective ChillAPI descriptor

The ChillAPI folder structure shall be created in the chose root directory, as follows:

• OpenAPI paths translated into directories, normalizing for compatibility
• One empty ChillAPI descriptor file for each method

Example:

paths:
  /article:
    get:
      summary: Get all articles
      operationId: getArticles
      ...
    post:
      tags:
        - article
      summary: Add an article
      operationId: addArticle
     ...
  '/article/{id}':
    put:
      tags:
        - article
      summary: Modify an article
      operationId: updateArticle
     ...
    delete:
      tags:
        - article
      summary: Delete an article
      operationId: deleteArticle
      ...

This OpenAPI spec fragment will generate the following directory structure:

..
\article
  GET.yaml
  POST.yaml
  \_id
    PUT.yaml
    DELETE.yaml

Note that {id} was transformed into _id for file system compatibility.

Each file content is filled using the descriptorContent function provided by the plugin.

Additionally, the generator creates a chillapi.lock.yaml file with hashes for each file written. The purpose is to determine, on each subsequent run of the generate goal, whether the file was modified by the client app, in order to avoid overwriting custom content.

For the above example, the yaml would be:

chillapi:
  - article:
    - GET.yaml: xxxxxxxxxxxxxxx
    - POST.yaml: xxxxxxxxxxxxxxx
    - _id:
      - PUT.yaml: xxxxxxxxxxxxxxx
      - DELETE.yaml: xxxxxxxxxxxxxxx

When attempting to write a file in the directory structure, the generator will perform the following logic:

• IF the file does not exist, THEN write it and append the hash to the lock file.
• IF the file exists, THEN
  • IF the file is present on the lock file, THEN
    • calculate the hash of the existing file
    • compare with the hash from the lock file
    • IF hashes are equal (i.e. file was generated and not modified by client app), THEN overwrite it
    • ELSE (file was modified by client app) skip
  • ELSE (file was created by client app) skip

Generate Server Implementation based on ChillAPI Config

Available options:

• rootDirectory:string: the location where the ChillAPI runtime should be saved; default ./runtime
• stepContent:function(step:any)=>{import:string,implementation:string}: a function that takes a step, as defined by the plugin in the ChillAPI configuration and generates the import section required to execute the step, as well as the actual code to be executed inside the Server implementation method

Note that, in case the stepContent function is missing, the import string will default to:

import {executeStep as myPluginName_executeStep} from 'myPluginName'

This assumes that the plugin exports a method with the signature executeStep(request, response, context)

The implementation will default to:

async function operation(request, response){
    const context: any = {};

    try{

    //... other steps
    // START IMPLEMENTATION DEFAULT

        const result = await myPluginName_executeStep(request, response, context);
        if(!!result){
            response.ok(result);
            return Promise.resolve();
        }

    // END IMPLEMENTATION DEFAULT
    //...other steps

    } catch(error){
        response
            .status(error?.status || 500)
            .send(error?.content || "Unexpected error");
        return Promise.resolve();
    }
    
    response.ok();
    return Promise.resolve();
}

A few notes on the step execution:

• The first step that resolves to a non-undefined value also returns from the HTTP method;
• If the step wants to return an error status, it should reject with an error object containing status and content
• If a step wants to pass variables to the next steps, it should use the context object available in the context of the entire operation