Theaninova/openstapps
1
0
Fork 0
mirror of https://gitlab.com/openstapps/openstapps.git synced 2026-02-28 11:52:13 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

feat: modernize core-tools

Browse Source
This commit is contained in:
Wieland Schöbl
2021-08-25 09:47:36 +00:00
parent 106dd26f89
commit fe59204b42
106 changed files with 4131 additions and 6216 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
README.md
View File

@@ -45,6 +45,15 @@ Inside of a script in `package.json` or if the npm package is installed globally
openstapps-core-tools schema src/core lib/schema
```
## What is Easy AST?
Easy [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) is a "wrapper" around the TypeScript Compiler API. The TS Compiler API is built for many
much more complex things than just accessing type declarations, and thus comes with a ton of
bloat that makes it really difficult to work with.
This is why we built the Easy AST, which converts the TS representation to a really easy and
lightweight structure, that removes a lot of the stuff you wouldn't really need.
## How to use the validator?
### Using the validator programatically
@@ -143,51 +152,6 @@ To pack all the different files into two distribution files - one for definition
openstapps-core-tools pack
```
## How to use the Elasticsearch Mapping generator
The mapping generator is intended to be used by the backend directly, but it can also be used to generate these files
manually.
### Generating the mapping files by hand
To generate the mapping files by hand, you need a local copy of the core-tools and the core, both need to be built first.
After that you can run
```
node lib/cli.js mapping path/to/core path/to/destination ignoredTag1,ignoredTag2,ignoredTag3
```
If you don't pass in any ignored tags, you will likely be prompted with errors, despite the core being absolutely correct.
This is because there are some tags that are not relevant to Elasticsearch, but the program has no direct way to tell
which ones simply lack an implementation and which ones can be ignored. Currently the ignored tags include
`minlength`, `pattern` and `see`.
### Generating the mapping directly from another TypeScript program
This is the more easy way, and it gives you direct access to the generated mapping as a (mostly typesafe) object. To
use it, call `generateTemplate`, However you will first need to generate a ProjectReflection of the core you are working
with. If you use the core as a dependency, you can for example use
```typescript
const map = generateTemplate(getProjectReflection(resolve('node_modules', '@openstapps', 'core', 'src')),
ignoredTags, false);
```
to generate the mappings. Note that the result object contains both a list of errors in `map.errors` and the actual mapping
in `map.template`. You can also specify whether you want the generator to show any errors while generating the mappings
in the console in the last parameter, `true` (default) being show errors and `false` to suppress them. That said it is very
easy to replace all `type: "MISSING_PREMAP"`, `type: "PARSE_ERROR"`, `type: "TYPE_CONFLICT"` with `dynamic: true` (you
can take these exactly like written here and run a replace over the file).
### Fixing a generated mapping by hand
If you get errors when generating the mappings, the mappings might not work, however they will still be generated to the
programs best efforts. Most small issues can be fixed after the mapping was generated as a temporary solution and without
changing anything in the mapper's code. This however requires some understanding of how mappings work.
The output of the program can easily reach 25.000 lines, but you can find errors quickly by searching for `MISSING_PREMAP`,
`PARSE_ERROR` and `TYPE_CONFLICT`. When you reach them you can then manually replace them with your code.
As a last resort you can also replace all errors with dynamic types, this should get the mapping working, but it is NOT
RECOMMENDED as a fix other than using it locally.
## How to use the UML generator
The UML Generator generates PlantUML from the project reflection of the source files. By default it will include externals, which will take considerably longer to execute, you can disable this behaviour via an option. It can help you to visually explore the data model or document a specific part.