Pine.js is a sophisticated rules-driven API engine that enables you to define rules in a structured subset of English. Those rules are used in order for Pine.js to generate a database schema and the associated OData API. This makes it very easy to rapidly create, update and maintain a backend while keeping the logic in an easily understood form, as well as providing the ability to update and maintain this logic going forward.
Rules are described in SBVR format, which stands for "Semantics of Business Vocabulary and Business Rules". SBVR provides a way to capture specifications in natural language and represent them in formal logic, so they can be machine processed.
The basic components of SBVR are as follows:
- Terms - these are the atomic elements of your data model, defined via
Term: [Term Name]. Generally speaking, these map to tables in a relational database, or attributes of other tables.
- Fact Types - these define relations between different terms and properties of those terms, e.g.
Fact type: pilot can fly planeor
Fact type: pilot is experienced- these somewhat map to fields and foreign keys in a relational database.
- Rules - these define logical constraints on the data model and is the most powerful aspect of SBVR and Pine.js itself. Rules map loosely to constraints in a relational database, but extend them to constraints that can traverse tables and generally be far more powerful than a database constraint. E.g.
Rule: It is obligatory that each pilot can fly at least 1 plane. The expressive capability of SBVR rules is much more than simple SQL DDL, and has the full power of First Order Logic.
As part of the @balena/pinejs package the following tools are installed:
- sbvr-compiler: Can be used to compile SBVR via the SBVR chain into SQL, eg
npx sbvr-compiler test.sbvr
- odata-compiler: Can be used to compile an OData URL via the OData chain from to SQL, eg
npx odata-compiler test.sbvr /test
Both tools use some of the main dependencies of Pine.js:
The above packages are written in
The following papers are also helpful in understanding the main concept of Pine.js:
The documentation inside /docs folder also provide a great overview of the main concepts of Pine.js, in particular:
- docs/Hooks.md: functions that you can implement in order to execute custom code when API calls are requested.
- docs/ProjectConfig.md: provides information regarding creating and configuring a project.
- docs/Types.md: types definitions and declarations in various systems.
- docs/sequence-diagrams/: provide a great overview of how the main processes are executed, including OData request parsing, response processing, etc. (The sequence diagrams can be depicted in websequencediagrams.com)
One can experiment with Pine.js, its main dependencies and the above tools inside the development environment of balena.
Where to go from here:
Start by creating your very first application with Pine.js. Jump to the Getting Started guide.