@artifacter/core v2.1.2

@artifacter/core

Artifacter's artifacts core generation service

Checkout Github's parsed README for a better visualization! -> https://github.com/arthmoeros/artifacter-core/

(If you are looking for the RESTful API, check @artifacter/webapi)

What's this? - Intro

This is Artifacter's core module (previously known as @artifacter/worker), it makes use of the template engine to build all the artifacts required via a Programmatic API. Artifacter provides any necessary details about its current configuration via this same API. On an artifact generation request, Artifacter will take its input and process it through its configuration, the outcome of this is a zip file, which is stored in a temporary folder until a get request is issued to retrieve this file.

How do I use this?

This is available as a npm package

npm install @artifacter/core

By default the config and temp directories are within the core base folder, you can customize these paths using the environment variables ARTIFACTER_CONFIG and ARTIFACTER_TMP, here is a unix example:

# Default is ./config
export ARTIFACTER_CONFIG=/etc/artifacter_custom
# Default is ./tmp
export ARTIFACTER_TMP=/var/artifacter_custom

What's in here? - API

Artifacter can be used as a Programmatic API, accesible via the Artifacter class, which contains the following methods:

Get Form Configurations list

Retrieves a list of presumably valid form configurations ids on the configuration path of Artifacter. It returns a string array containing each form configuration ID (file name without extension).

Get Form Configuration

Retrieves the contents of an identified form configuration file on Artifacter as a generic object.

Request Artifact Generation

Requests an artifact generation and returns an uuid to retrieve the generated artifacts.

Retrieve generated artifacts

Retrieves a generated artifact, once is retrieved it is deleted from the temp folder, any subsequent try to get the same artifact will result in a 404 not found error.

How do I make a Form Configuration? - Form Configuration "Schema"

Form Configurations in Artifacter are JSON files with expected properties to define how a client can request an artifact generation, this file will be explained using the sample configuration bundled with it.

Forms

The root of each Form Configuration is a forms array, each contains a name, description and input data required to be submitted. A forms begins like this:

{
    /* 
        A forms array, each one represent a possible input for a single blueprint and task,
        it is suggested that one group of forms = 1 blueprint.
    */
    "$forms": [ 
        {
            /*
                A display name and description for the Form
            */
            "$formName": "Sample Form 1",
            "$formDescription": "Blah blah blah...",

Request Schema

This is 'like' a Schema, and since there is no yet a single decent json schema parser in npm (and the specification is not finished), this one will do for now. At its base has static data for internal referencing, such as its own form configuration json file name, generation name and its underlying task name, these must be provided as is in each request that uses this structure. Artifacter expects this data to work. The rest of the structure is what it should be expected when a request for artifact generation is submitted along with the before mentioned static data, except each last child in each hierarchy, which have a type definition and miscellaneous information, such as:

Input Display Data

Additional metadata for the input definition, this defines how can the input data be labeled and further supported, this information is essential for a better understanding of the data required by the form.

Declared Post Processors

Declared post processors for the submitted values, these are run by Artifacter before any template processing, just after recieving the request.

Artifacter for now supports these:

• string.allLowerCase
• string.allUpperCase
• string.startWithUpperCase
• string.startWithLowerCase
• string.blanksToCamelCase

I saw something about a Blueprint? - Blueprint "Schema"

Just like the Form Configuration json files, there are Blueprint json files, these contains tasks that can be executed for a corresponding artifact generation. There is a sample packaged with the application.

Each task can contain a subset of instructions for the internal blueprint processor to read and execute, these instructions have their underlying properties, can be nested and represent the outcoming structure of the artifacts generated for each task. Some properties uses the same template engine and request values for processing template'd values.

Anything else I should know? - Other info

Yes, the expected Artifacter configuration must follow this structure:

• ARTIFACTER_CONFIG (default is './config')
  • blueprint-material
    • blueprint-folder (the matching folders names for each blueprint json, that contains all necessary templates and static files for each task of the blueprint)
  • blueprint
    • blueprint-json (blueprints json files, explained above)
  • form
    • form-json (form configuration json files, explained above too)

If you need an example for this structure and its files, check out the sample provided here, if you want a sample request from the sample request schema, check out this json file

If you need an User Interface for this, use @artifacter/ui in conjunction with @artifacter/webapi instead of this package alone

What's coming next? - Planned features for a future release

Not much, this is a second version and I already covered pretty much everything I wanted to achieve, it is still lacking a configuration validation check and maybe some queued generation with some queue framework, also I thought about a security layer and migrating the configuration storage to a MongoDB, if you have any other suggestion I would gladly hear you out, along with a use case.