Ronas IT Angular Common

Common Angular services for communicating with backend, authentication and user managing.

Live demo

In progress...

About the library

Ronas IT Angular Common working with cookies. One of the main advantages of this approach is that cookies can be HTTP-only. It makes them read-protected on the client side, that improves safety against any Cross-site scripting (XSS) attacks. Cookie-based authentication allows using this services in Server-Side Rendering (SSR) applications.

Getting Started

Installation

Install Ronas IT Angular Common:

npm i @ronas-it/angular-common --save

Usage

ApiModule

1. Add ApiModule to AppModule imports:

import { ApiModule } from '@ronas-it/angular-common';
import { configuration } from '@configuration';

@NgModule({
  imports: [
    ApiModule.forRoot({
      apiUrl: configuration.api.url
    }),
    ...
  ],
  ...
})
export class AppModule { }

2. Inject ApiService and use it:

import { ApiService } from '@ronas-it/angular-common';
import { Injectable } from '@angular/core';

@Injectable()
export class ProductService {
  constructor(
    private apiService: ApiService
  ) { }

  public delete(id: number): Observable<void> {
    return this.apiService.delete(`/products/${id}`);
  }

  ...
}

CookieModule

1. Add CookieModule to AppModule imports:

import { CookieModule } from '@ronas-it/angular-common';

@NgModule({
  imports: [
    CookieModule.forRoot({
      defaultOptions: { path: '/', /* other cookie options ... */ }
    }),
    ...
  ],
  ...
})
export class AppModule { }

2. Inject CookieService and use it:

import { BehaviorSubject, Subject } from 'rxjs';
import { CookieService } from '@ronas-it/angular-common';
import { Injectable } from '@angular/core';

@Injectable()
export class CookiePopupFacade {
  private isCookiesAccepted$: Subject<boolean>;

  constructor(
    private cookieService: CookieService
  ) { 
    this.isCookiesAccepted$ = new BehaviorSubject(this.cookieService.get('isCookiesAccepted') === 'true');
  }

  public acceptCookies(): void {
    this.isCookiesAccepted$.next(true);

    this.cookieService.put('isCookiesAccepted', 'true', { maxAge: 4e10 });
  }

  ...
}

3. (SSR Only) Add providers for REQUEST and RESPONSE injection tokens from @nguniversal/express-engine/tokens in server.ts:

server.get('*', (req, res) => {
  res.render(indexHtml, {
    req,
    res,
    providers: [
      {
        provide: APP_BASE_HREF,
        useValue: req.baseUrl
      },
      {
        provide: REQUEST,
        useValue: req
      },
      {
        provide: RESPONSE,
        useValue: res
      }
    ]
  });
});

4. (SSR Only) Set requestToken and responseToken parameters in the CookieModule config:

import { CookieModule } from '@ronas-it/angular-common';
import { REQUEST, RESPONSE } from '@nguniversal/express-engine/tokens';

@NgModule({
  imports: [
    CookieModule.forRoot({
      defaultOptions: { /* ... */ },
      requestToken: REQUEST,
      responseToken: RESPONSE
    }),
    ...
  ],
  ...
})
export class AppModule { }

UserModule

Note: This module depends on ApiModule and AuthModule. Please make sure to install them prior to installing this module.

1. Create a User model and extend it from AbstractUser:

import { AbstractUser } from '@ronas-it/angular-common';
import { Expose } from 'class-transformer';

export class User extends AbstractUser {
  @Expose({ groups: ['main'] })
  public id: number;

  @Expose({ groups: ['main'] })
  public name: string;

  @Expose({ groups: ['main'] })
  public email: string;
}

2. Create a UserService and extend it from CommonUserService:

import { UserService as CommonUserService } from '@ronas-it/angular-common';

@Injectable()
export class UserService extends CommonUserService<User> {
  /* Define custom methods or override existing methods here. */
}

3. Create a UserModule and add CommonUserModule to imports:

import { NgModule } from '@angular/core';
import { User } from './models';
import { UserModule as CommonUserModule } from '@ronas-it/angular-common';
import { UserService } from './user.service';

@NgModule({
  imports: [
    CommonUserModule.forRoot({
      userModel: User,
      userService: UserService
    }),
    ...
  ],
  ...
})
export class UserModule { }

4. Inject UserService and use it:

import { Action } from '@ngrx/store';
import { Actions, createEffect, ofType } from '@ngrx/effects';
import { AuthService } from '@shared/auth';
import { catchError, filter, mergeMap, switchMap, withLatestFrom } from 'rxjs/operators';
import { HttpErrorResponse } from '@angular/common/http';
import { Injectable } from '@angular/core';
import { Observable, of } from 'rxjs';
import { User } from '../models';
import { userActions } from './actions';
import { UserService } from '../user.service';

@Injectable()
export class UserEffects {
  public refreshProfile$: Observable<Action> = createEffect(
    () => this.actions$.pipe(
      ofType(userActions.refreshProfile),
      withLatestFrom(this.authService.isAuthenticated$),
      filter(([_, isAuthenticated]) => isAuthenticated),
      switchMap(() => {
        return this.userService.refreshProfile()
          .pipe(
            mergeMap((user: User) => [
              userActions.updateProfile({ profile: user }),
              userActions.refreshProfileSuccess()
            ]),
            catchError((response: HttpErrorResponse) => of(userActions.refreshProfileFailure({ response })))
          );
      })
    )
  );

  constructor(
    private actions$: Actions,
    private authService: AuthService,
    private userService: UserService
  ) { }
}

AuthModule

Note: This module depends on ApiModule, CookieModule and UserModule. Please make sure to install them prior to installing this module.

1. Create an AuthService and extend it from CommonAuthService:

import { AuthService as CommonAuthService } from '@ronas-it/angular-common';
import { Injectable } from '@angular/core';
import { User } from '@shared/user';

@Injectable()
export class AuthService extends CommonAuthService<User> {
  /* Define custom methods or override existing methods here. */
}

2. Create an AuthModule and add CommonAuthModule to imports:

import { AuthModule as CommonAuthModule } from '@ronas-it/angular-common';
import { AuthService } from './auth.service';
import { configuration } from '@configuration';
import { NgModule } from '@angular/core';

@NgModule({
  imports: [
    CommonAuthModule.forRoot({
      unauthorizedRoutes: configuration.api.unauthorized_routes,
      authService: AuthService,

      // Optionally, you can pass `unauthenticatedRoute` parameter that
      // specifies the route to redirect to after logout or when a user is
      // not authenticated to view some page. By default it is set to `/login`.
      unauthenticatedRoute: '/'
    }),
    ...
  ],
  ...
})
export class AuthModule { }

3. Inject AuthService and use it:

import { Action } from '@ngrx/store';
import { Actions, createEffect, ofType } from '@ngrx/effects';
import { authActions } from './actions';
import { AuthService } from '../auth.service';
import { catchError, exhaustMap, map } from 'rxjs/operators';
import { Injectable } from '@angular/core';
import { Observable, of } from 'rxjs';

@Injectable()
export class AuthEffects {
  public authorize$: Observable<Action> = createEffect(
    () => this.actions$.pipe(
      ofType(authActions.authorize),
      exhaustMap((action) => {
        return this.authService
          .authorize(action.credentials)
          .pipe(
            map((response) => authActions.authSuccess({ response })),
            catchError((response) => of(authActions.authFailure({ response })))
          );
      })
    )
  );

  constructor(
    private actions$: Actions,
    private authService: AuthService
  ) { }
}

API

ApiModule

Config

ApiModule.forRoot(config: ApiConfig)

ApiConfig

Name | Type | Required | Description --- | --- | --- | --- apiUrl | string | Yes | Endpoint that allows you to access an API trailingSlash | boolean | No | The need for trailing slash (https://api.your-service.com/login/ for example) enableArrayKeys | boolean | No | Enabling array keys for http params fileKeys | Array<string> | No | List of the file keys for http params

ApiService

Field | Type --- | --- apiUrl | string trailingSlash | string fileKeys | Array<string>

Method | Arguments | Return type --- | --- | --- get<T> | endpoint: string, params: any, options: object | Observable<T> post<T> | endpoint: string, data: any, options: object | Observable<T> put<T> | endpoint: string, data: any, options: object | Observable<T> delete<T> | endpoint: string, params: any, options: object | Observable<T>

CookieModule

Config

CookieModule.forRoot(config: CookieConfig)

CookieConfig

Name | Type | Required | Description --- | --- | --- | --- defaultOptions | CookieOptions | No | Cookie options that will be used if not specified in the put method requestToken | InjectionToken<Request> | No | Request injection token from @nguniversal/express-engine/tokens for cookies support in SSR responseToken | InjectionToken<Response> | No | Response injection token from @nguniversal/express-engine/tokens for cookies support in SSR

CookieOptions

Name | Type --- | --- maxAge | number expires | Date path | string domain | string secure | boolean sameSite | boolean \| 'lax' \| 'strict' \| 'none'

CookieService<TKey extends string = string>

Field | Type --- | --- cookieString | string

Method | Arguments | Return type --- | --- | --- get | key: TKey | string \| null getObject | key: TKey | object \| null getAll | | Record<string, string> hasKey | key: TKey | boolean put | key: TKey, value: string, options?: CookieOptions | void putObject | key: TKey, value: object, options?: CookieOptions | void remove | key: TKey, options?: CookieOptions | void removeAll | options?: CookieOptions | void

AuthModule

Config

CommonAuthModule.forRoot(config: AuthConfig)

AuthConfig

Name | Type | Required | Description --- | --- | --- | --- unauthorizedRoutes | Array<string> | Yes | Routes that don't need authorization (public routes, e.g. login, registration and forgot password pages) authService | new (...args: Array<any>) => any | Yes | Service that will be used in your app unauthenticatedRoute | string | No | Route to redirect to after logout or when a user is not authenticated to view some page. By default it is set to /login disableRedirectAfterUnauthorize | boolean | No | Whether to redirect to unauthenticatedRoute after logout or when a user is not authenticated to view some page. By default it is set to false authenticatedRoute | string | No | Route to redirect after successful login loginEndpoint | string | No | Endpoint for login, e.g. /api/token refreshTokenEndpoint | string | No | Endpoint for refreshing token, e.g. /api/token/refresh refreshTokenEndpointMethod | 'get' \| 'post' | No | HTTP Method that will be used for calling endpoint to refresh token isAuthenticatedField | string | No | Field for cookie rememberField | string | No | Field for cookie cookiesExpirationDays | number | No | Expiration for authentication cookies when call authorize with remember flag set to true. By default it is set to 365

AuthService<User extends AbstractUser>

Static constant | Type --- | --- DEFAULT_LOGIN_ENDPOINT | string DEFAULT_UNAUTHENTICATED_ROUTE | string DEFAULT_IS_AUTHENTICATED_FIELD | string DEFAULT_REFRESH_TOKEN_ENDPOINT | string DEFAULT_REMEMBER_FIELD | string DEFAULT_COOKIES_EXPIRATION_DAYS | number

Field | Type --- | --- isTokenRefreshing$ | Observable<boolean> isAuthenticated$ | Observable<boolean> cookiesExpiresDate | Date

Method | Arguments | Return type --- | --- | --- authorize<T> | credentials: AuthCredentials & T, remember: boolean | Observable<AuthResponse<User>> manuallyAuthorize | authResponse: object, remember: boolean = true | Observable<AuthResponse<User>> unauthorize | | void refreshToken | | Observable<HttpResponse<void>> setIsAuthenticated | remember: boolean | void resetIsAuthenticated | | void resetRemember | | void

AuthCredentials

Field | Type | Required --- | --- | --- email | string | No password | string | Yes

AuthResponse<User extends AbstractUser>

Field | Type | Required --- | --- | --- user | User | No

UserModule

Config

UserModule.forRoot(config: UserConfig)

UserConfig

Name | Type | Required | Description --- | --- | --- | --- userModel | new (user: any) => any | Yes | Model (class) for user userService | new (...args: Array<any>) => any | Yes | Your UserService implementation profileRelations | Array<string> | No | Relations for getting profile request. For example: /profile?with[]=company&with[]=clients profileRelationsKey | string | No | with by default

UserService<User extends AbstractUser>

Field | Type --- | --- profile$ | Observable<User>

Method | Arguments | Return type --- | --- | --- refreshProfile | | Observable<User> loadProfile | | Observable<User> updateProfile | user: User | Observable<void> updatePassword | userPasswords: UserPasswords | Observable<void> setProfile | user: User | void patchProfile | user: Partial<User> | void resetRemember | | void resetProfile | | void userToPlain | user: User, options?: ClassTransformOptions | Object plainToUser | plain: object, options?: ClassTransformOptions | User

AbstractUser

Field | Type | Required --- | --- | --- id | number \| string | Yes

Contributing

Contributions to Ronas IT Angular Common are welcome. The contribution guide can be found in the Contributing guide.

License

Ronas IT Angular Common is open-sourced software licensed under the MIT license.