@openstapps/core-tools

@openstapps/core-tools

Tools to convert and validate StAppsCore

What are the tools for?

The StAppsCore Converter is a tool for converting SC-types (TypeScript) into JSON schema files.

JSON schema files are needed for run-time validation of SC-type objects, as this is a tedious task to do using SC-types defined in TypeScript (not possible without additional coding). That said, StAppsCore Converter practically prepares SC-types to be used for object validation (determining whether a JavaScript/JSON object is a valid object of the corresponding SC-type) using StAppsCore Validator.

The StAppsCore Validator is a tool for run-time validation of objects (determining whether a JavaScript/JSON object is a valid object of the corresponding SC-type. It consumes JSON schema files from StAppsCore as the definitions of SC-types against which are validated concrete (actual) objects (as an example SCDish object in the example below).

Installation

Installation of the npm package (using npm install) makes the tool available as an executable with the name openstapps-core-tools.

How to use the converter?

Add @validatable to the Typedoc comment of the types that you want to convert to JSONSchema.

The command openstapps-core-tools can then be called using these arguments:

openstapps-core-tools schema <srcPath> <schemaPath>

where:

• <srcPath> is path to the project (where used *.ts files are, e.g. src/core,
• <schemaPath> is directory to save output files to, e.g. lib/schema.

Complete command with the example arguments is then:

openstapps-core-tools schema src/core lib/schema

Inside of a script in package.json or if the npm package is installed globally, the tool stapps-convert can be called without its local path (node_modules/.bin):

openstapps-core-tools schema src/core lib/schema

How to use the validator?

Using the validator programatically

import {Validator} from '@openstapps/core-tools';
import {SCDish, SCThingType} from '@openstapps/core';
import {ValidatorResult} from 'jsonschema';
import {join} from 'path';

const objectToValidate: SCDish = {
type: SCThingType.Dish,
// more properties
};

// instantiate a new validator
const validator = new Validator();

// make the validator read the schema files
validator.addSchemas(join('node_modules', '@openstapps', 'core', 'lib', 'schema')).then(() => {
  // validate an object
  const result: ValidatorResult = validator.validate(objectToValidate, 'SCDish');
});

Using validateFiles function

The JSON files passed to the validateFiles method have an added layer. That layer encapsulates the actual JSON data of the object to be verified and adds a property to enable true negative testing.

Your basic JSON object:

{
  "property1": "value1",
  "property2": "value2",
  ...
}

JSON for validateFiles:

{
  "errorNames": [],
  "instance": {
    "property1": "value1",
    "property2": "value2",
    ...
  },
  "schema": "NameOfSchema"
}

Where errorNames holds the string values of the name property of the expected ValidationErrors from JSON Schema. Empty array means no errors are expected.

schema holds the name of the schema to validate the instance against.

How to use validator as a CLI tool (executable)?

The command openstapps-core-tools can then be called using these arguments:

openstapps-core-tools validate <schemaPath> <testPath> [reportPath]

where:

• <schemaPath> is a directory where JSON schema files are, e.g. lib/schema,
• <testPath> is a directory where test files are, e.g. src/test/resources,
• [reportPath] is a file where the HTML report of the validation will be saved to, e.g. report.html (optional argument - if it's not provided no report will be written).

Command with the example arguments is then for example:

openstapps-core-tools validate lib/schema src/test/resources

Inside of a script in package.json or if the npm package is installed globally, the tool openstapps-validate can be called without its local path (node_modules/.bin):

openstapps-core-tools validate lib/schema src/test/resources report.html

Generate documentation for routes

To generate a documentation for the routes use the following command.

openstapps-core-tools routes PATH/TO/CORE/lib PATH/TO/ROUTES.md

Pack definitions and implementations

To pack all the different files into two distribution files - one for definitions/one for implementations - use the following command:

openstapps-core-tools pack

Changelog

0.4.0 (2019-04-03)

Features

• add feature to validate schemas directly (1022150)
• adjust generation of route documentation (d3ce936), closes #12