@balena/pinejs 14.51.1 → 14.51.2

package/.versionbot/CHANGELOG.yml

@@ -1,3 +1,20 @@
+- commits:
+    - subject: "Docs: Improve getting started doc"
+      hash: ee7df5cc1793438b8cc69b37607677fb7256e887
+      body: |
+        Give preference to TypeScript over CoffeeScript for the example app.
+        Improve code blocks by giving them types and removing unnecessary
+        characters to enable better copy-paste when viewing on GitHub.
+      footer:
+        Change-type: patch
+        change-type: patch
+        Signed-off-by: Josh Bowling <josh@monarci.com>
+        signed-off-by: Josh Bowling <josh@monarci.com>
+      author: Josh Bowling
+      nested: []
+  version: 14.51.2
+  title: ""
+  date: 2022-11-02T00:51:06.545Z
 - commits:
     - subject: "Docs: Fix TypeScript getting started example"
       hash: 491a79b281ed551cdf174412df7466cf411befb4
@@ -11,7 +28,7 @@
       nested: []
   version: 14.51.1
   title: ""
-  date: 2022-11-01T06:47:04.345Z
+  date: 2022-11-01T06:55:17.123Z
 - commits:
     - subject: Update lodash typings
       hash: 734fd4c97f9438df4d2f80430739a4f1036e62cf

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file
 automatically by Versionist. DO NOT EDIT THIS FILE MANUALLY!
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+# v14.51.2
+## (2022-11-02)
+
+* Docs: Improve getting started doc [Josh Bowling]
+
 # v14.51.1
 ## (2022-11-01)
 

package/VERSION

@@ -1 +1 @@
-14.51.1
+14.51.2

package/docs/GettingStarted.md

@@ -8,30 +8,30 @@ Let's create a new Pine.js application. We will see that by defining our model r
 
 To begin with, you'll need to install PostgreSQL on your system, and configure a database and a user with read/write/metadata permissions on the database. In this guide, we will use `example` as the database name and `exampler` as the user name. Open your favorite terminal and type the following commands:
 
-```
-$ createuser -W exampler
-$ createdb example -O exampler
+```sh
+createuser -W exampler
+createdb example -O exampler
 ```
 
 The above commands will create a user with name `exampler` and will prompt for a password, and then will set `exampler` as the database owner. You can also use your favorite tool to achieve the same result, such as pgAdmin.
 
 Next you'll need to install Pine.js as a dependency of your application. Go to a new directory that will use for your application. Let's say `pine-get-started` and type:
 
-```
-$ npm init
+```sh
+npm init
 ```
 
 Feel free to enter any information you like for your application when prompted, like application name, version, description, etc. The above command will initialize your application by creating the `package.json` file.
 
-```
-$ npm install --save @balena/pinejs
+```sh
+npm install @balena/pinejs
 ```
 
 The above commands will install pinejs as a dependency for your application, i.e. it will create the node_modules directory that amongst others will contain Pine.js, and will update the corresponding record in your `package.json` file.
 
 Let's see what your directory looks like now:
 
-```
+```sh
 $ tree -L 3
 .
 ├── node_modules
@@ -44,7 +44,7 @@ Now, create a directory for our source files, `src` and enter that directory.
 
 First, we have to create a configuration file, `config.json` that will provide to Pine.js the necessary configuration regarding the resource model and the user permissions. Open your favorite editor and type the following into the `config.json` file:
 
-```
+```json
 {
 	"models": [{
 			  "modelName": "Example",
@@ -89,19 +89,55 @@ Fact Type: device has type
 
 In this model we are defining an entity called `device`, this entity has some attributes such as `name`, `note` and `type`, along with some constraints, ensuring that a device must have exactly one device type, and at most one name and one note. The `Vocabulary` declaration is a convenient way for partitioning parts of larger sbvr files.
 
-### Initialise a CoffeeScript project
+### Initialise a TypeScript project
 
 Now, let's create a small main file for our application that will call the Pine.js server. Let's install some basic dependencies:
+Create a small main file for our application that will call the Pine.js server. Let's install some basic dependencies:
 
+```sh
+npm install express body-parser
+npm install -D typescript ts-node @types/express
 ```
-$ npm install --save coffeescript
-$ npm install --save express
-$ npm install --save body-parser
+
+And inside your `src` folder, create a file `app.ts` with the following content:
+
+```typescript
+import express, { Request, Response } from 'express';
+import * as pine from '@balena/pinejs';
+
+const app = express();
+app.use(express.urlencoded({ extended: true }));
+app.use(express.json());
+
+app.use('/ping', (_req: Request, res: Response) => {
+	res.sendStatus(200);
+});
+
+pine.init(app).then(() => {
+    app.listen(1337, () => {
+        console.log('server started');
+    });
+});
 ```
 
-And inside your `src` folder, create a file `app.coffee` with the following content:
+Inside your `package.json` file enter the following line inside the section `scripts`:
 
 ```
+"start": "ts-node src/app.ts src"
+```
+
+### Initialise a CoffeeScript project
+
+Alternatively, here's an example of the same small application written in CoffeeScript.  
+Install some basic dependencies:
+
+```sh
+npm install coffeescript express body-parser
+```
+
+And inside your `src` folder, create a file `app.coffee` with the following content:
+
+```coffeescript
 pinejs = require '@balena/pinejs'
 express = require 'express'
 app = express()
@@ -120,7 +156,6 @@ pinejs.init(app)
 		console.info('Server started')
 ```
 
-
 Finally, inside your `package.json` file enter the following line inside the section `scripts`:
 
 ```
@@ -129,7 +164,7 @@ Finally, inside your `package.json` file enter the following line inside the sec
 
 Let's see what our application directory looks like now:
 
-```
+```sh
 $ tree -L 3
 .
 ├── node_modules
@@ -169,44 +204,12 @@ $ tree -L 3
     └── example.sbvr
 ```
 
-### Initialise a TypeScript project
-
-```sh
-npm install express body-parser
-npm install -D typescript ts-node @types/express
-```
-
-```typescript
-import express, { Request, Response } from 'express';
-import * as pine from '@balena/pinejs';
-
-const app = express();
-app.use(express.urlencoded({ extended: true }));
-app.use(express.json());
-
-app.use('/ping', (_req: Request, res: Response) => {
-	res.sendStatus(200);
-});
-
-pine.init(app).then(() => {
-    app.listen(1337, () => {
-        console.log('server started');
-    });
-});
-```
-
-Inside your `package.json` file enter the following line inside the section `scripts`:
-
-```
-"start": "ts-node src/app.ts src"
-```
-
 ### Start the server
 
 Assuming postgreSQL is running, execute the following command, replacing `[your_password]` with the password you set for the user `exampler`.
 
-```
-$ DATABASE_URL=postgres://exampler:[your_password]@localhost:5432/example npm start
+```sh
+DATABASE_URL=postgres://exampler:[your_password]@localhost:5432/example npm start
 ```
 
 Pine.js will connect to the `example` database and it will create the database schema and the associated API endpoints. Once the server is up, use your favourite tool, such as pgAdmin, to connect to the database and take a look inside. Among the other things, you will find that Pine.js has created a table called `device`, which will contain the devices we earlier specified in the model. By inspecting the structure of this table, you can see that the constraints specified in sbvr model get directly translated to constraints in the underlying database.
@@ -221,8 +224,8 @@ We will use cURL to make these requests, so open up another terminal window and
 
 First of all we need to create a device. To do so type the following in the new window:
 
-```
-$ curl -X POST -d name=testdevice -d note=testnote -d type=raspberry http://localhost:1337/example/device
+```sh
+curl -X POST -d name=testdevice -d note=testnote -d type=raspberry http://localhost:1337/example/device
 ```
 
 If the creation succeeds the server will respond with an object representing the new entity, in this case it will look something like this:
@@ -235,14 +238,14 @@ Aside from `__metadata` which is used internally, the properties of this object
 
 If we ask the server for a list of devices we will see the one we just created:
 
-```
-$ curl -X GET http://localhost:1337/example/device
+```sh
+curl -X GET http://localhost:1337/example/device
 ```
 
 The server will respond with an array containing all the devices, if we want to access a specific one, it is sufficient to add the id at the end of the URL we pass.
 
-```
-$ curl -X GET 'http://localhost:1337/example/device(1)'
+```sh
+curl -X GET 'http://localhost:1337/example/device(1)'
 ```
 
 The above cURL request will return the single entity with `id=1`.
@@ -250,8 +253,8 @@ The above cURL request will return the single entity with `id=1`.
 To modify the device we just created: the OData specification tells us that to do so we can make a `PUT` request to the endpoint that represents the entity.
 Lets try this:
 
-```
-$ curl -X PUT -d name=testdevice -d note=updatednote 'http://localhost:1337/example/device(1)'
+```sh
+curl -X PUT -d name=testdevice -d note=updatednote 'http://localhost:1337/example/device(1)'
 
 ***
 Internal Server Error
@@ -261,8 +264,8 @@ What went wrong here? Pine.js is simply preventing us from violating the constra
 
 To correctly modify the device we can try:
 
-```
-$ curl -X PUT -d name=testdevice -d note=updatednote -d type=raspberry 'http://localhost:1337/example/device(1)'
+```sh
+curl -X PUT -d name=testdevice -d note=updatednote -d type=raspberry 'http://localhost:1337/example/device(1)'
 ```
 
 You can now try to delete this entity to restore the database to it’s initial state. Recall from the OData specification that this can be done by performing a DELETE request at the endpoint represented by the entity we intend to delete.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@balena/pinejs",
-  "version": "14.51.1",
+  "version": "14.51.2",
   "main": "out/server-glue/module",
   "repository": "git@github.com:balena-io/pinejs.git",
   "license": "Apache-2.0",
@@ -141,6 +141,6 @@
     "recursive": true
   },
   "versionist": {
-    "publishedAt": "2022-11-01T06:47:05.037Z"
+    "publishedAt": "2022-11-02T00:51:07.406Z"
   }
 }