@gigster/module-loopback-models NPM

loopback-models

Role	Name	Email	Slack
Product Owner	Ryan Borker	borker@gigster.com	@borker
Maintainer	Jerome Curlier	jerome@gigster.com	@jerome
Contributor	Mark Miyashita	mark.miyashita@gigster.com	@mark

Overview

This module maps the project models defined in gig.yaml to the Loopback model format.

Usage

- name: loopback-models
  location: https://github.com/liquidlabs-co/gig-modules/tree/master/block/loopback-models
  spec:
    defaultDatasource: fileDs
    defaultEmailDatasource: email
    generateTests: true
    models:
      - name: user
        methods:
          enabled:
            - create
            - patchOrCreate
            - replaceOrCreate

Specification

Name	Status
defaultDatasource	Default datasource to be used by the models when no datasource is defined for them
defaultEmailDatasource	Default email datasource
generateTests	Set to true to generate model tests (unit + API tests)
enabled	Methods to enable, disable all others, see Method visibility.
disabled	Methods to disable, enable all others, see Method visibility.

Endpoints

The modules generate the endpoinds for the CRUD opertations on the models:

Endpoint	Method	Description
POST /users	create	Create a new instance of the model and persist it into the data source
PATCH /users	patchOrCreate	Patch an existing model instance or insert a new one into the data source
PUT /users	replaceOrCreate	Replace an existing model instance or insert a new one into the data source
POST /users/{id}	replaceOrCreate	Replace an existing model instance or insert a new one into the data source
HEAD /users/{id}	exists	Check whether a model instance exists in the data source
GET /users/{id}	exists	Check whether a model instance exists in the data source
GET /users/{id}	findById	Find a model instance by {{id}} from the data source
PUT /users/{id}	replaceById	Replace attributes for a model instance and persist it into the data source.
POST /users/{id}/replace	replaceById	Replace attributes for a model instance and persist it into the data source
GET /users	find	Find all instances of the model matched by filter from the data source.
GET /users/{id}	findOne	Find first instance of the model matched by filter from the data source.
POST /users/{id}	updateAll	Update instances of the model matched by {{where}} from the data source.
DELETE /users/{id}	deleteById	Delete a model instance by {{id}} from the data source
GET /users/count	count	Count instances of the model matched by where from the data source
PATCH /users/{id}	prototype.patchAttributes	Patch attributes for a model instance and persist it into the data source

The list does not show the Loopback streaming endpoints, as well as the endpoints provided by the relationship between models (see Loopback documentation).

The Loopback explorer provides a Swagger interface to the endpoints.

Explorer Methods

Note: Methods can be enabled and disabled through the module configuration.

Method visibility

By default all the methods generated by Loopback and defined in the project are enabled.

If you would like to disable one or several methods, set the name of the methods in the disabled specification for a given model.
If you would like to only enable one or several methods, set the name of the methods in the enabled specification for a given model.

You can only use either disabled or enabled. disabled configuration will take precedence over enabled.

See the section Find the enable method names to log the name of the methods. The Loopback explorer interface provides the method name on mouseover.

Dependencies

The following npm packages are used (only if one of the datasource defined requires it):

npm	version
loopback-connector-mongodb	^3.3.0
loopback-connector-mysql	^5.2.0
loopback-connector-postgresql	^3.2.0

Database

The datasources section specify the database used by the model.

Name	Status
name	Name of the datasource
type	Type of the datasource (one of email, file, memory, mongodb, mysql, postgresql
spec	Configuration for the datasource

See Creating a database schema from models

Sample datasources configuration

datasources:
   - name: mysqlDs
     type: mysql
     spec:
       host: DATABASE_MYSQL_HOST
       port: DATABASE_MYSQL_PORT
       database: DATABASE_MYSQL_DATABASE
       user: DATABASE_MYSQL_USER
       password: DATABASE_MYSQL_PASSWORD
   - name: mongoDs
     type: mongodb
     spec:
       url: DATABASE_MONGODB_URL
   - name: postgresqlDs
     type: postgresql
     spec:
       host: DATABASE_POSTGRESQL_HOST
       port: DATABASE_POSTGRESQL_PORT
       database: DATABASE_POSTGRESQL_DATABASE
       user: DATABASE_POSTGRESQL_USER
       password: DATABASE_POSTGRESQL_PASSWORD
   - name: email
     type: email
     spec:
       host: EMAIL_HOST
       port: EMAIL_PORT
       secure: EMAIL_SECURE
       user: EMAIL_USER
       password: EMAIL_PASSWORD
   - name: memoryDs
     type: memory
   - name: fileDs
     type: file

Note that:

we can have a default datasource as specified by the module specification.
we can have a different datasource for each model even if the models are related.

Utilities

Name	Description	Command
`create.js`	Uses Loopback automigrate to create a database	`DEBUG=loopback:models node ./database/create.js`
`update.js`	Uses Loopback autoupdate to update a database schmea	`DEBUG=loopback:models node ./database/update.js`

See Creating a database schema from models

MongoDB

Configuration

  - name: mongodbDs
    type: mongodb
    spec:
      host: GIG_HOST
      port: GIG_PORT
      url: GIG_URL
      database: GIG_DATABASE

The values in uppercase are the name of the environment variables to get the information at runtime.

Docker

docker pull mongo
docker run -p 27017:27017 --name mongo -d mongo

MySQL

Configuration

  - name: myqlDs
    type: mysql
    spec:
      host: GIG_HOST
      port: GIG_PORT
      url: GIG_URL
      database: GIG_DATABASE

The values in uppercase are the name of the environment variables to get the information at runtime.

Docker

docker pull mysql
docker run -p 3306:3306 --name some-mysql -e MYSQL_ROOT_PASSWORD=passw0rd -d mysql

Note: A databse needs to be ceated first.

mysql --protocol=TCP -u root -p

CREATE SCHEMA `test` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

PostgreSQL

  - name: postgreslqDs
    type: postgreslq
    spec:
      host: GIG_HOST
      port: GIG_PORT
      url: GIG_URL
      database: GIG_DATABASE

The values in uppercase are the name of the environment variables to get the information at runtime.

Docker

docker pull postgres:latest
docker run -p 5432:5432 -e POSTGRES_PASSWORD=mysecretpassword -d postgres

Please login into postgres using the user postgres

psql postgres://127.0.0.1:5432 -U postgres

CREATE DATABASE `test`;

Memory

This datasource uses the memory to maintain the data, and therefore the data is lost when the application is stopped.

Configuration

  - name: memoryDs
    type: memory

File

The datasource uses the file db.json to maintain the data. The file is located at the root of the project.

Configuration

  - name: fileDs
    type: file

Email

Configuration

- name: email
    type: email
    spec:
      host: EMAIL_HOST
      port: EMAIL_PORT
      secure: EMAIL_SECURE
      user: EMAIL_USER
      password: EMAIL_PASSWORD

The name must be email and only one configuration is supported.

The values in uppercase are the name of the environment variables to get the information at runtime.

Generation

Models

For each model, the module generates the Loopback model.json and model.jsm a file for each custom method - using the method skeleton of the model - and one validation file.

Database

The module generates two files in the database folder to create and update database schemas.

Name	Status
create.js	Uses Loopback automigrate to create a database
update.js	Uses Loopback autoupdate to update a database schmea

The configuration for the datasources is generated in the file datasources.local.js.

Tests

Module tests are defined using a test/scenarios.yaml file. This file defines the set of example gigs that we generate as part of integration testing. To run all tests, run yarn test at the root of this module.

Each scenario is generated in test/scenario/<name> which you can then cd into and run the actual app. For a scenario called default, this is done via:

cd test/scenario/default
yarn install

# Run tests.
yarn test

# Start the app.
yarn start

Troubleshooting

DEBUG=gdt:loopback:models npm start

Find the enable method names

DEBUG=loopback:contrib:setup-remote-methods-mixin npm start

Appendix

Project definition support

The following table list the attributes from the project defintion that are mapped by the module.

Name	Status
name	:white_check_mark:
datasource	:white_check_mark:
description	:white_check_mark:
type	:white_check_mark:
default	:white_check_mark:
defaultFn	:white_check_mark:
unique	:white_check_mark:
id	:white_check_mark:
obscured	:x:
nullable	:x:
hidden	:white_check_mark:

Validation

Name	Status
required	:white_check_mark:
min	:white_check_mark:
max	:white_check_mark:
pattern	:white_check_mark:
enum	:white_check_mark:
format	:x:

ACLs

Name	Status
accessType	:white_check_mark:
method	:white_check_mark:
permission	:white_check_mark:
principalId	:white_check_mark:
principalType	:white_check_mark:

Datasources

Name	Status
name	:white_check_mark:
type	:white_check_mark:
spec	:white_check_mark:

Indexes

Name	Status
name	:white_check_mark:
keys	:white_check_mark:
unique	:white_check_mark:

Methods

Name	Status
description	:white_check_mark:
input	:white_check_mark:
name	:white_check_mark:
notes	:white_check_mark:
output	:white_check_mark:

Options for API

Name	Status
method	:white_check_mark:
description	:white_check_mark:
errorStatus	:white_check_mark:
input	:white_check_mark:
input name	:white_check_mark:
input source	:white_check_mark:
name	:white_check_mark:
path	:white_check_mark:
status	:white_check_mark:
verb	:white_check_mark:

Relations

Name	Status
name	:white_check_mark:
type	:white_check_mark:
model	:white_check_mark:
primaryKey	:white_check_mark:
foreignKey	:white_check_mark:
through	:white_check_mark:
keyThrough	:white_check_mark: