@gigster/module-loopback-models

Role | Name | Email | Slack ---- | ---- | ----- | ----- *Product Owner* | Ryan Borker | [borker@gigster.com](mailto:boker@gigster.com) | [@borker] *Maintainer* | Jerome Curlier | [jerome@gigster.com](mailto:jerome@gigster.com) | [@jerome] *Contributor* |

Stats

StarsIssuesVersionUpdatedCreatedSize
@gigster/module-loopback-models
1.2.134 years ago4 years agoMinified + gzip package size for @gigster/module-loopback-models in KB

Readme

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:

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.