Merge pull request #702 from FoalTS/v1-9-0

v1.9.0

.github/CONTRIBUTING.MD

@@ -127,7 +127,7 @@ Here is the list of its sub-directories:
 | Directory | Description |
 | --- | --- |
 | generators | Contains the code which renders the templates or updates the files |
-| mocks | Contains some pieces of code used to test the file "updaters" |
+| fixtures | Contains some pieces of code used to test the file "updaters" |
 | specs | Defines how the generated files should look like in different scenarios (specifications) |
 | templates | Contains the actual templates used to generate the files |
 | utils | Contains some helpers shared by all the generators |

.github/workflows/test.yml

@@ -16,9 +16,6 @@ jobs:
         node-version: [8, 10]
 
     env:
-      AUTH0_DOMAIN: ${{ secrets.AUTH0_DOMAIN }}
-      AUTH0_AUDIENCE: ${{ secrets.AUTH0_AUDIENCE }}
-      AUTH0_TOKEN: ${{ secrets.AUTH0_TOKEN }}
       SETTINGS_AWS_ACCESS_KEY_ID: ${{ secrets.SETTINGS_AWS_ACCESS_KEY_ID }}
       SETTINGS_AWS_SECRET_ACCESS_KEY: ${{ secrets.SETTINGS_AWS_SECRET_ACCESS_KEY }}
       NODE_VERSION: ${{ matrix.node-version }}

docs/SUMMARY.md

@@ -38,10 +38,10 @@
   * [Hooks](./architecture/hooks.md)
   * [Initialization](./architecture/initialization.md)
 * Databases
-  * [TypeORM (SQL & noSQL)](./databases/typeorm.md)
+  * [SQL Databases (TypeORM)](./databases/typeorm.md)
   * [Create Models & Queries](./databases/create-models-and-queries.md)
   * [Generate & Run Migrations](./databases/generate-and-run-migrations.md)
-  * [Use Mongoose (MongoDB)](./databases/using-mongoose.md)
+  * [MongoDB (TypeORM or Mongoose)](./databases/mongodb.md)
   * [Use Another ORM](./databases/using-another-orm.md)
 * Authentication & Access Control
   * [Quick Start](./authentication-and-access-control/quick-start.md)

docs/api-section/rest-blueprints.md

@@ -5,10 +5,10 @@
 foal generate rest-api product --register
 ```
 
-Building a REST API is often a common task when creating an application. To avoid reinventing the wheel, FoalTS provides an integrated command to achieve this.
+Building a REST API is often a common task when creating an application. To avoid reinventing the wheel, FoalTS provides a CLI command to achieve this.
 
 ```
-foal generate rest-api <name> [--register]
+foal generate rest-api <name> [--register] [--auth]
 ```
 
 This command generates three files: an entity, a controller and the controller's test. Depending on your directory structure, they may be generated in different locations:
@@ -116,7 +116,18 @@ export const productSchhema = {
 };
 ```
 
-## Generate OpenAPI documentation
+## Using Authentication
+
+If you wish to attach a user to the resource, you can use the `--auth` flag to do so.
+
+*Example:*
+```
+foal generate rest-api product --auth
+```
+
+This flags adds an `owner: User` column to your entity and uses it in the API.
+
+## Generating OpenAPI documentation
 
 The generated controllers also have OpenAPI decorators on their methods to document the API.
 

docs/architecture/controllers.md

@@ -120,7 +120,7 @@ import { Context, HttpResponseCreated, Post } from '@foal/core';
 class AppController {
   @Post('/products')
   createProduct(ctx: Context) {
-    const requestBody = ctx.request.body;
+    const body = ctx.request.body;
     // Do something.
     return new HttpResponseCreated();
   }
@@ -140,7 +140,7 @@ import { Context, HttpResponseOK, Post } from '@foal/core';
 
 class AppController {
   @Get('/products/:id')
-  createProduct(ctx: Context) {
+  readProduct(ctx: Context) {
     const productId = ctx.request.params.id;
     // Do something.
     return new HttpResponseOK(/* something */);
@@ -161,7 +161,7 @@ import { Context, HttpResponseOK, Post } from '@foal/core';
 
 class AppController {
   @Get('/products')
-  createProduct(ctx: Context) {
+  readProducts(ctx: Context) {
     const limit = ctx.request.query.limit;
     // Do something.
     return new HttpResponseOK(/* something */);
@@ -201,6 +201,25 @@ class AppController {
 }
 ```
 
+
+#### The Controller Method Arguments
+
+> Available in Foal v1.9.0 onwards.
+
+The path paramaters and request body are also passed as second and third arguments to the controller method.
+
+```typescript
+import { Context, HttpResponseCreated, Put } from '@foal/core';
+
+class AppController {
+  @Put('/products/:id')
+  updateProduct(ctx: Context, { id }, body) {
+    // Do something.
+    return new HttpResponseCreated();
+  }
+}
+```
+
 ## HTTP Responses
 
 HTTP responses are defined using `HttpResponse` objects. Each controller method must return an instance of this class (or a *promise* of this instance).

docs/databases/mongodb.md

@@ -0,0 +1,139 @@
+# MongoDB
+
+FoalTS provides two ways to interact with a MongoDB database in your application: [Mongoose](https://mongoosejs.com/) and [TypeORM](https://typeorm.io/#/).
+
+## Usage with Mongoose
+
+### Generating a new project with Mongoose
+
+When creating an application with the `--mongodb` flag, the CLI generates a new project with `mongoose` and `@foal/mongoose` installed. The `User` model is defined using this ODM as well as the `create-user` script.
+
+```
+foal createapp my-app --mongodb
+```
+
+### Generating a model
+
+You cannot create *entities* in a Mongoose project, as it is specific to TypeORM. Instead, you can use this command to generate a new model:
+
+```
+foal g model <name>
+```
+
+### Configuration
+
+The URI of the MongoDB database can be passed through:
+- the config file `config/default.json` with the `mongodb.uri` key,
+- or with the environment variable `MONGODB_URI`.
+
+*Example (`config/default.json`)*:
+```json
+{
+  ...
+  "mongodb": {
+    "uri": "mongodb://localhost:27017/db"
+  }
+}
+```
+
+### Authentication
+
+#### The `MongoDBStore`
+
+```
+npm install @foal/mongodb
+```
+
+If you use sessions with `@TokenRequired` or `@TokenOptional`, you must use the `MongoDBStore` from `@foal/mongodb`.
+
+#### The `fetchUser` function
+
+*Example with JSON Web Tokens*:
+```typescript
+import { JWTRequired } from '@foal/jwt';
+import { fetchUser } from '@foal/mongoose';
+
+import { User } from '../models';
+
+@JWTRequired({ user: fetchUser(User) })
+class MyController {}
+```
+
+## Usage with TypeORM
+
+```
+npm uninstall sqlite3
+npm install mongodb
+```
+
+### Configuration
+
+*ormconfig.js*
+```js
+const { Config } = require('@foal/core');
+
+module.exports = {
+  type: "mongodb",
+  database: Config.get2('database.database', 'string'),
+  dropSchema: Config.get2('database.dropSchema', 'boolean', false),
+  entities: ["build/app/**/*.entity.js"],
+  host: Config.get2('database.host', 'string'),
+  port: Config.get2('database.port', 'number'),
+  synchronize: Config.get2('database.synchronize', 'boolean', false)
+}
+
+```
+
+
+*config/default.json*
+```json
+{
+  "database": {
+    "database": "mydb",
+    "host": "localhost",
+    "port": 27017
+  }
+}
+```
+
+### Authentication
+
+#### The `MongoDBStore`
+
+```
+npm install @foal/mongodb
+```
+
+If you use sessions with `@TokenRequired` or `@TokenOptional`, you must use the `MongoDBStore` from `@foal/mongodb`. **The TypeORMStore does not work with noSQL databases.**
+
+#### The `fetchMongoDBUser` function
+
+*user.entity.ts*
+```typescript
+import { Entity, ObjectID, ObjectIdColumn } from 'typeorm';
+
+@Entity()
+export class User {
+
+  @ObjectIdColumn()
+  id: ObjectID;
+
+}
+```
+
+*Example with JSON Web Tokens*:
+```typescript
+import { JWTRequired } from '@foal/jwt';
+import { fetchMongoDBUser } from '@foal/typeorm';
+
+import { User } from '../entities';
+
+@JWTRequired({ user: fetchMongoDBUser(User) })
+class MyController {}
+```
+
+## Limitations
+
+When using MongoDB, there are some features that are not available:
+- the `foal g rest-api <name>` command,
+- and the *Groups & Permissions* system.

docs/databases/typeorm.md

@@ -1,5 +1,7 @@
 # TypeORM
 
+> *FoalTS components using TypeORM officially support the following databases: PostgreSQL, MySQL, MariaDB and SQLite*.
+
 *A simple model:*
 ```typescript
 import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';