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 plane or 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.
In order to get an idea of how SBVR works, visit the sbvr lab, and for more details, check out the SBVR spec.
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:
- abstract-sql-compiler
- lf-to-abstract-sql
- sbvr-parser
- odata-parser
- odata-to-abstract-sql
The above packages are written in OMeta and compiled into Javascript. The following resources consitute a good starting point in order for someone to get a better understanding of OMeta and the above dependencies:
- OMeta paper
- OMeta slides
- Introduction to OMeta-js
- OMeta workspace
- Related blog posts
The following papers are also helpful in understanding the main concept of Pine.js:
- An SBVR to SQL Compiler
- Generating SQL Queries from SBVR Rules
The documentation inside /docs folder also provide a great overview of the main concepts of Pine.js, in particular:
- docs/Migrations.md: provides information regarding sql queries or Javascript functions that are executed prior to pinejs executing a given SBVR model.
- 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.
Storing files and other large objects
An application can choose between two types to save file content or another large object: File or WebResource. When using a File, PineJS saves the content in the database using a binary data type like BYTEA or BLOB. When using a WebResource, PineJS saves the binary content on an external storage service and then writes metadata, including the content public URL, to the database. Client apps use the WebResource href to get the content.
Please note that WebResource is still a work in progress and as such has a few limitations. Such as (but not exclusively):
- Filtering for specific filenames or size
- Deletion of a file may fail and will require to manually delete the file from its storage
