mirror of
https://gitlab.com/openstapps/openstapps.git
synced 2026-01-07 14:02:48 +00:00
145 lines
5.1 KiB
Markdown
145 lines
5.1 KiB
Markdown
# @openstapps/core-tools
|
|
|
|
[](https://gitlab.com/openstapps/core-tools/commits/master)
|
|
[](https://npmjs.com/package/@openstapps/core-tools)
|
|
[](https://www.gnu.org/licenses/gpl-3.0.en.html)
|
|
[](https://openstapps.gitlab.io/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:
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
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`):
|
|
|
|
```shell
|
|
openstapps-core-tools schema src/core lib/schema
|
|
```
|
|
|
|
## How to use the validator?
|
|
|
|
### Using the validator programatically
|
|
|
|
```typescript
|
|
import {Validator} from '@openstapps/core-tools/lib/validate';
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"property1": "value1",
|
|
"property2": "value2",
|
|
...
|
|
}
|
|
```
|
|
|
|
JSON for validateFiles:
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
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`):
|
|
|
|
```shell
|
|
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.
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
openstapps-core-tools pack
|
|
```
|