Merge pull request #1073 from FoalTS/null-contexts

Improve `Context` class interface

docs/docs/architecture/controllers.md

@@ -100,9 +100,9 @@ It has four properties:
 | Name | Type | Description |
 | --- | --- | --- |
 | `request` | `Request` | Gives information about the HTTP request. |
-| `state` | object | Object which can be used to forward data accross several hooks (see [Hooks](./hooks.md)). |
-| `user` | `any\|undefined` | The current user (see [Authentication](../authentication-and-access-control/quick-start.md)). | 
-| `session`| `Session\|undefined` | The session object if you use sessions. |
+| `state` | `{ [key: string]: any }` | Object which can be used to forward data accross several hooks (see [Hooks](./hooks.md)). |
+| `user` | `{ [key: string]: any }\|null` | The current user (see [Authentication](../authentication-and-access-control/quick-start.md)). | 
+| `session`| `Session\|null` | The session object if you use sessions. |
 
 
 ### HTTP Requests

docs/docs/architecture/hooks.md

@@ -395,7 +395,7 @@ export class UserService {
   };
 
   getUser(key: string) {
-    return this.users[key];
+    return this.users[key] ?? null;
   }
 }
 
@@ -494,7 +494,7 @@ interface State {
 
 export class ApiController {
   // ...
-  readOrgName(ctx: Context<any, any, State>) {
+  readOrgName(ctx: Context<any, State>) {
     // ...
   }
 }

docs/docs/authentication-and-access-control/administrators-and-roles.md

@@ -33,7 +33,7 @@ import { Context, Hook, HttpResponseForbidden, HttpResponseUnauthorized } from '
 import { User } from '../entities';
 
 export function AdminRequired() {
-  return Hook((ctx: Context<User>) => {
+  return Hook((ctx: Context<User|null>) => {
     if (!ctx.user) {
       return new HttpResponseUnauthorized();
     }
@@ -88,7 +88,7 @@ import { Context, Hook, HttpResponseForbidden, HttpResponseUnauthorized } from '
 import { User } from '../entities';
 
 export function RoleRequired(role: string) {
-  return Hook((ctx: Context<User>) => {
+  return Hook((ctx: Context<User|null>) => {
     if (!ctx.user) {
       return new HttpResponseUnauthorized();
     }

docs/docs/authentication-and-access-control/groups-and-permissions.md

@@ -340,7 +340,7 @@ export class ProductController {
 
 | Context | Response |
 | --- | --- |
-| `ctx.user` is undefined | 401 - UNAUTHORIZED |
+| `ctx.user` is null | 401 - UNAUTHORIZED |
 | `ctx.user.hasPerm('perm')` is false | 403 - FORBIDDEN |
 
 ```typescript
@@ -349,7 +349,7 @@ export class ProductController {
 
 | Context | Response |
 | --- | --- |
-| `ctx.user` is undefined | Redirects to `/login` (302 - FOUND) |
+| `ctx.user` is null | Redirects to `/login` (302 - FOUND) |
 | `ctx.user.hasPerm('perm')` is false | 403 - FORBIDDEN |
 
 *Example*

docs/docs/authentication-and-access-control/quick-start.md

@@ -140,7 +140,7 @@ export class AppController implements IAppController {
 
 *src/app/controllers/auth.controller.ts*
 ```typescript
-import { Context, hashPassword, HttpResponseOK, HttpResponseUnauthorized, Post, Session, ValidateBody, verifyPassword } from '@foal/core';
+import { Context, hashPassword, HttpResponseOK, HttpResponseUnauthorized, Post, ValidateBody, verifyPassword } from '@foal/core';
 
 import { User } from '../entities';
 
@@ -158,21 +158,21 @@ export class AuthController {
 
   @Post('/signup')
   @ValidateBody(credentialsSchema)
-  async signup(ctx: Context<any, Session>) {
+  async signup(ctx: Context) {
     const user = new User();
     user.email = ctx.request.body.email;
     user.password = await hashPassword(ctx.request.body.password);
     await user.save();
 
-    ctx.session.setUser(user);
-    await ctx.session.regenerateID();
+    ctx.session!.setUser(user);
+    await ctx.session!.regenerateID();
 
     return new HttpResponseOK();
   }
 
   @Post('/login')
   @ValidateBody(credentialsSchema)
-  async login(ctx: Context<any, Session>) {
+  async login(ctx: Context) {
     const user = await User.findOne({ email: ctx.request.body.email });
 
     if (!user) {
@@ -183,15 +183,15 @@ export class AuthController {
       return new HttpResponseUnauthorized();
     }
 
-    ctx.session.setUser(user);
-    await ctx.session.regenerateID();
+    ctx.session!.setUser(user);
+    await ctx.session!.regenerateID();
 
     return new HttpResponseOK();
   }
 
   @Post('/logout')
-  async logout(ctx: Context<any, Session>) {
-    await ctx.session.destroy();
+  async logout(ctx: Context) {
+    await ctx.session!.destroy();
 
     return new HttpResponseOK();
   }
@@ -719,7 +719,7 @@ npm run migrations
 
 *src/app/app.controller.ts*
 ```typescript
-import { Context, controller, dependency, Get, IAppController, render, Session, Store, UserRequired, UseSessions } from '@foal/core';
+import { Context, controller, dependency, Get, IAppController, render, Store, UserRequired, UseSessions } from '@foal/core';
 import { fetchUser } from '@foal/typeorm';
 import { createConnection } from 'typeorm';
 
@@ -751,9 +751,9 @@ export class AppController implements IAppController {
   }
 
   @Get('/login')
-  login(ctx: Context<any, Session>) {
+  login(ctx: Context) {
     return render('./templates/login.html', {
-      errorMessage: ctx.session.get<string>('errorMessage', '')
+      errorMessage: ctx.session!.get<string>('errorMessage', '')
     });
   }
 
@@ -762,7 +762,7 @@ export class AppController implements IAppController {
 
 *src/app/controllers/auth.controller.ts*
 ```typescript
-import { Context, hashPassword, HttpResponseRedirect, Post, Session, ValidateBody, verifyPassword } from '@foal/core';
+import { Context, hashPassword, HttpResponseRedirect, Post, ValidateBody, verifyPassword } from '@foal/core';
 
 import { User } from '../entities';
 
@@ -780,42 +780,42 @@ export class AuthController {
 
   @Post('/signup')
   @ValidateBody(credentialsSchema)
-  async signup(ctx: Context<any, Session>) {
+  async signup(ctx: Context) {
     const user = new User();
     user.email = ctx.request.body.email;
     user.password = await hashPassword(ctx.request.body.password);
     await user.save();
 
-    ctx.session.setUser(user);
-    await ctx.session.regenerateID();
+    ctx.session!.setUser(user);
+    await ctx.session!.regenerateID();
 
     return new HttpResponseRedirect('/');
   }
 
   @Post('/login')
   @ValidateBody(credentialsSchema)
-  async login(ctx: Context<any, Session>) {
+  async login(ctx: Context) {
     const user = await User.findOne({ email: ctx.request.body.email });
 
     if (!user) {
-      ctx.session.set('errorMessage', 'Unknown email.', { flash: true });
+      ctx.session!.set('errorMessage', 'Unknown email.', { flash: true });
       return new HttpResponseRedirect('/login');
     }
 
     if (!await verifyPassword(ctx.request.body.password, user.password)) {
-      ctx.session.set('errorMessage', 'Invalid password.', { flash: true });
+      ctx.session!.set('errorMessage', 'Invalid password.', { flash: true });
       return new HttpResponseRedirect('/login');
     }
 
-    ctx.session.setUser(user);
-    await ctx.session.regenerateID();
+    ctx.session!.setUser(user);
+    await ctx.session!.regenerateID();
 
     return new HttpResponseRedirect('/');
   }
 
   @Post('/logout')
-  async logout(ctx: Context<any, Session>) {
-    await ctx.session.destroy();
+  async logout(ctx: Context) {
+    await ctx.session!.destroy();
 
     return new HttpResponseRedirect('/login');
   }

docs/docs/authentication-and-access-control/session-tokens.md

@@ -398,9 +398,9 @@ export class ApiController {
   }
 
   @Get('/products')
-  readProducts(ctx: Context) {
+  readProducts(ctx: Context<User>) {
     // If the ctx.session is defined and the session is attached to a user
-    // then ctx.user is an instance of User. Otherwise it is undefined.
+    // then ctx.user is an instance of User. Otherwise it is null.
     return new HttpResponseOK([]);
   }
 
@@ -493,7 +493,7 @@ In the following example, the `user` cookie is empty if no user is logged in or
 *Server-side code*
 
 ```typescript
-function userToJSON(user: User|undefined) {
+function userToJSON(user: User|null) {
   if (!user) {
     return 'null';
   }
@@ -507,13 +507,13 @@ function userToJSON(user: User|undefined) {
 @UseSessions({
   cookie: true,
   user: fetchUser(User),
-  userCookie: (ctx, services) => userToJSON(ctx.user)
+  userCookie: (ctx, services) => userToJSON(ctx.user as User|null)
 })
 export class ApiController {
 
   @Get('/products')
   @UserRequired()
-  async readProducts(ctx: Context) {
+  async readProducts(ctx: Context<User>) {
     const products = await Product.find({ owner: ctx.user });
     return new HttpResponseOK(products);
   }
@@ -537,20 +537,20 @@ const user = JSON.parse(decodeURIComponent(/* cookie value */));
 You can access and modify the session content with the `set` and `get` methods.
 
 ```typescript
-import { Context, HttpResponseNoContent, Post, Session, UseSessions } from '@foal/core';
+import { Context, HttpResponseNoContent, Post, UseSessions } from '@foal/core';
 
 @UseSessions(/* ... */)
 export class ApiController {
 
   @Post('/subscribe')
-  subscribe(ctx: Context<any, Session>) {
-    const plan = ctx.session.get<string>('plan', 'free');
+  subscribe(ctx: Context) {
+    const plan = ctx.session!.get<string>('plan', 'free');
     // ...
   }
 
   @Post('/choose-premium-plan')
-  choosePremimumPlan(ctx: Context<any, Session>) {
-    ctx.session.set('plan', 'premium');
+  choosePremimumPlan(ctx: Context) {
+    ctx.session!.set('plan', 'premium');
     return new HttpResponseNoContent();
   }
 }
@@ -899,10 +899,10 @@ interface SessionState {
 The function `fetchUser` from the package `@foal/typeorm` takes an `@Entity()` class as parameter and returns a function with this signature:
 
 ```typescript
-type FetchUser = (id: string|number, services: ServiceManager) => Promise<any>
+type FetchUser = (id: string|number, services: ServiceManager) => Promise<Context['user']>
 ```
 
-If the ID matches a user, then an instance of the class is returned. Otherwise, the function returns `undefined`.
+If the ID matches a user, then an instance of the class is returned. Otherwise, the function returns `null`.
 
 If needed you can implement your own `fetchUser` function with this exact signature.
 

docs/docs/authentication-and-access-control/social-auth.md

@@ -194,7 +194,6 @@ import {
   dependency,
   Get,
   HttpResponseRedirect,
-  Session,
   Store,
   UseSessions,
 } from '@foal/core';
@@ -218,7 +217,7 @@ export class AuthController {
   @UseSessions({
     cookie: true,
   })
-  async handleGoogleRedirection(ctx: Context<User, Session>) {
+  async handleGoogleRedirection(ctx: Context<User>) {
     const { userInfo } = await this.google.getUserInfo<{ email: string }>(ctx);
 
     if (!userInfo.email) {
@@ -234,7 +233,7 @@ export class AuthController {
       await user.save();
     }
 
-    ctx.session.setUser(user);
+    ctx.session!.setUser(user);
 
     return new HttpResponseRedirect('/');
   }

docs/docs/databases/using-another-orm.md

@@ -29,7 +29,7 @@ To do so, you will have to remove TypeORM and all its utilities and implement so
 
 If you wish to use the `user` option of `@JWTRequired` or `@UseSessions` to set the `ctx.user` property, then you will need to implement your own `fetchUser` function.
 
-This utility returns a function that takes an `id` as parameter which might be a `string` or a `number` and returns a promise. The promise value must be `undefined` is no user matches the given `id` and the *user object* otherwise.
+This utility returns a function that takes an `id` as parameter which might be a `string` or a `number` and returns a promise. The promise value must be `null` is no user matches the given `id` and the *user object* otherwise.
 
 *Example*
 ```typescript
@@ -41,9 +41,6 @@ export function fetchUser(userModel: any): FetchUser {
       throw new Error('The user ID must be a number.');
     }
     const user = await userModel.findOne({ id });
-    if (user === null) {
-      return undefined;
-    }
     return user;
   };
 }

docs/docs/security/csrf-protection.md

@@ -374,13 +374,10 @@ import {
   dependency,
   Get,
   render,
-  Session,
   Store,
   UseSessions,
 } from '@foal/core';
 
-import { User } from '../entities';
-
 export class ViewController {
   @dependency
   store: Store;
@@ -396,10 +393,10 @@ export class ViewController {
     required: true,
     redirectTo: '/login'
   })
-  async index(ctx: Context<User, Session>) {
+  async index(ctx: Context) {
     return render(
       './templates/products.html',
-      { csrfToken: ctx.session.get('csrfToken') },
+      { csrfToken: ctx.session!.get('csrfToken') },
     );
   }
 }

docs/docs/tutorials/real-world-example-with-react/10-auth-with-react.md

@@ -53,7 +53,7 @@ import { Context } from '@foal/core';
 @UseSessions({
   cookie: true,
   user: fetchUser(User),
-  userCookie: (ctx: Context<User|undefined>) => ctx.user ? JSON.stringify({ id: ctx.user.id, name: ctx.user.name }) : '',
+  userCookie: (ctx) => ctx.user ? JSON.stringify({ id: ctx.user.id, name: ctx.user.name }) : '',
 })
 ```
 

docs/docs/tutorials/real-world-example-with-react/11-sign-up.md

@@ -13,7 +13,7 @@ So far, only users created with the `create-user` script can log in and publish
 Open the `auth.controller.ts` file and add a new route.
 
 ```typescript
-import { Context, hashPassword, HttpResponseNoContent, HttpResponseOK, HttpResponseUnauthorized, Post, Session, ValidateBody, verifyPassword } from '@foal/core';
+import { Context, hashPassword, HttpResponseNoContent, HttpResponseOK, HttpResponseUnauthorized, Post, ValidateBody, verifyPassword } from '@foal/core';
 import { User } from '../../entities';
 
 const credentialsSchema = {
@@ -28,7 +28,7 @@ export class AuthController {
 
   @Post('/signup')
   @ValidateBody(credentialsSchema)
-  async signup(ctx: Context<User|undefined, Session>) {
+  async signup(ctx: Context<User|null>) {
     const email = ctx.request.body.email;
     const password = ctx.request.body.password;
 
@@ -39,7 +39,7 @@ export class AuthController {
     user.password = await hashPassword(password);
     await user.save();
 
-    ctx.session.setUser(user);
+    ctx.session!.setUser(user);
     ctx.user = user;
 
     return new HttpResponseOK({

docs/docs/tutorials/real-world-example-with-react/12-file-upload.md

@@ -59,7 +59,7 @@ export class ProfileController {
 
   @Get('/avatar')
   @ValidateQueryParam('userId', { type: 'number' }, { required: false })
-  async readProfileImage(ctx: Context<User|undefined>) {
+  async readProfileImage(ctx: Context<User|null>) {
     let user = ctx.user;
 
     const userId: number|undefined = ctx.request.query.userId;