@genese/angular

v2.0.1

Published

3 years ago

Angular library which allows you to remove data-services and DTO mappers. This module is a part of the @genese framework.

Downloads

0High
0Medium
0Low

gillesfabre

@genese/angular @genese/mapper dto genese angular services

@genese/angular

@genese/angular is an Angular library which allows you to remove your data-services and your DTO mappers. This module is a part of the @genese framework.

Simple example using @genese/angular: @genese/angular-demo

Why use @genese/angular ?

@genese/angular is a powerful tool which will improve your productivity in building web apps.

This module will allow you to remove all your Angular data-services. It replaces the http requests located in your services, and replaces the mappers used to format data coming from the backend into typed objects.

Returning typed objects from your data-services to your components is fundamental : if you do not, your component could receive incorrect data from the backend, and your application would crash automatically. That's why the mappers are so important. Unfortunately, writing mappers is long and fastidious. More, you need to write unit tests for your mappers, and add some mock values to be able to do these tests. Idem for your http requests, which should be tested with some tools like HttMock. That's why writing data-services is so long and fastidious.

So, what would you say if Genese could do all of that for you ? Yes, that's right : @genese/angular calls the http requests for you, and uses a Generic mapper which will send you back objects automatically typed ! In the next example, that means that you can simply destroy the file book-data.service.ts and put it in the garbage, with its associated test file book-data.service.spec.ts.

Example

Actually, you probably have Angular data-services like this :

book.model.ts

export class Book = {
    id?: string;
    isAvailable?: boolean;
    name?: string;
    public editors?: [{
        name?: string,
        country.: string
    }];

    constructor() {}
}

book-data.service.ts

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { map } from 'rxjs/operators';

@Injectable({
    providedIn: 'root'
})
export class BookDataService {

    constructor(private http: HttpClient) {}

    mapToBook(data: any): Book {
        let book = new Book();
        if (data && data.id) {
            book.id = data.id;
            book.isAvailable : data.isAvailable ? data.isAvailable : false;
            book.name : data.name ? data.name : '';
            book.editors = [];
            if (Array.isArray(data.editors)) {
                for (let editor of data.editors) {
                    let newEditor = {};
                    newEditor.name = editor.name ? editor.name : '';
                    newEditor.country = editor.country ? editor.country : '';
                    book.editors.push(newEditor);
                }
            }
        }
        return book;
    }

    getOne(id: string): Observable<Book> {
        this.http.get('http://localhost:3000/' + id)
            .pipe(
                map((data: any) => {
                    return this.mapToBook(data);
                }
            )
    }

    getAll(): Observable<Book[]> {
        this.http.get('http://localhost:3000/')
            .pipe(
                map((data: any) => {
                    let books = [];
                    if (Array.isArray(data)) {
                        for (let element of data) {
                            books.push(this.mapToBook(element));
                        }
                    }
                    return books;
                }
            )
    }

    delete(id: string) {
        // call DELETE request and do some stuff
    }

    update(id: string) {
        // call PUT request and do some stuff
    }

    // other CRUD methods
}

With @genese/angular, you can put this file in the garbage, simply by calling GeneseService inside your components, like this :

Supposing that in your environment.ts, genese.api = http://localhost:3000 .

books.component.ts

export class BooksComponent {

    public booksGenese: Genese<Book>;

    constructor(private geneseService: GeneseService) {
        this.booksGenese = geneseService.getGeneseInstance(Book);
    }

    this.booksGenese.getOne('/books', '1').subscribe((book: Book) => {
    // book is the data returned by 
    // the request http://localhost:3000/books/1
    // and formatted with type Book
});
}

With the getOne() Genese method, you are sure to receive your data correctly formatted with Book's type. No data-services to write, and no unit tests to do. Of course, you can use all the classic CRUD methods with Genese, but you can do much more : translate automatically the properties of your objects, paginate automatically lists coming from your getAll() requests, etc.

With Genese, you simply code better and faster.

Top

Installation

At first you need to install the npm module:

npm install angular --save

The minimum Angular version is Angular 8.

Top -> Installation

1. Config

Now, you need to configure your environment. Genese needs to know what is the api address of your backend. You can do that by adding GeneseEnvironmentService in the constructor of your AppComponent.

Example:

app.component.ts

import { Component } from '@angular/core';
import { GeneseEnvironmentService } from 'angular';
import { environment } from '../environments/environment';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.scss']
})
export class AppComponent {

    constructor(geneseEnvironmentService: GeneseEnvironmentService) {
        geneseEnvironmentService.setEnvironment(environment.genese);
    }
}

environment.ts

export const environment = {
    production: false,
    genese: {
        api: 'http://localhost:3000'
    }
};

(replace the value of the property api by your api url)

Top -> Installation

2. Import Genese module

Import the genese module in the app.module.

Example

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';
import { GeneseModule } from 'angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        GeneseModule.forRoot(),

        AppRoutingModule
    ],
    bootstrap: [AppComponent]
})
export class AppModule { }

Top -> Installation

3. Inject geneseService in your component

Add a property with Genese type to your component, inject GeneseService in the constructor and instantiate your property with getGeneseInstance.

Example

import { Book } from './models/book.model.ts';
import { Genese } from 'angular/lib/factories/genese.factory';
import { GeneseService } from 'angular';

@Component({
    selector: 'app-home',
    templateUrl: './home.component.html',
    styleUrls: ['./home.component.scss']
})
export class HomeComponent {

    public booksGenese: Genese<Book>;

    constructor(
        private geneseService: GeneseService,
    ) {
        this.booksGenese = geneseService.getGeneseInstance(Book);
    }
}

Top

Models

Genese needs to be able to find all the properties of your models. That's why it is imperative to set default values to all the properties of your models, including inside nested objects. Respecting this constraint, Genese will be able to return all the objects correctly formatted.

Optional

getOne() and getAll() methods are "cleaner" than getOneCustom() and getAllCustom() because they hide the path of the endpoints in your components. If you want to use them, you must specify the desired route in the model :

export class Book = {
    id ?= '';
    name ?= '';
    public genese?: GeneseModelEnvironment = {
        path: '/books'
    };
}

Note

A Genese good practice is to set all the properties of your models as optional. It will be easier to create new objects and will not crash if one day you forget to set a property.

Top -> Models

Primitives

Example with primitives

export class Book = {
    id ?= '';
    codeNumbers: number[] = [0];
    collectionNumber?: 0;
    isAvailable?: true;
    name ?= '';
}

Top -> Models

Nested objects

Example with nested object

export class Book = {
    id ?= '';
    public editor?: {
        name?: string,
        place?: {
            city?: string,
            country?: string
        }
    } = {
        name: '',
        place: {
            city: '',
            country: ''
        }
    };
}

Top -> Models

Indexable types

Suppose that you wait http responses like this

{
    en: 'The caves of steel',
        fr: 'Les cavernes d\'acier'
}

and suppose that you don't know in advance how many properties will have your response. In this example, you don't know in advance how many translations you will receive and in which languages. In this case, you need to use indexable types like this :

export class Book = {
    [key: string]: string
}

This is the simplest example of indexable types. Now, suppose that your http request returns something more complex like this :

{
    en: {
        country: 'England',
            name: 'The caves of steel'
    },
    fr: {
        country: 'France',
            name: 'Les cavernes d\'acier'
    }
}

In this case, you simply need to define your Genese model like this :

export class Book = {
    [key: string]: {
    country?: string,
        name?: string
} = {
    gnIndexableType: {
        country: '',
        name: ''
    }
}
}

The gnIndexableType key is a special key used by Genese to understand that you wait a response with indexableTypes. You'll need to use it every time you'll have to use indexable types.

Top -> Models

Translations

Supposing that you have some fields which are translated in many languages, you'll probably want to have a GET request which will return the object translated in one of these languages. For example, if your data are like this

{
    en: {
        country: 'England',
            name: 'The caves of steel'
    },
    fr: {
        country: 'France',
            name: 'Les cavernes d\'acier'
    }
}

you may want to receive a response with only the french language, like this :

{
    country: 'France',
        name: 'Les cavernes d\'acier'
}

Genese can do that for you. You will need to use the translate() method, which is described here. To be able to do that, you need to construct your model like this :

export class Book = {
    gnTranslate: {
        [key: string]: {
    country: string,
        name: string
}
} = {
    gnIndexableType: {
        country: '',
        name: ''
    }
}
}

The gnTranslate key is a specific keyword used by Genese to understand that some fields may be translated. You'll need to use it every time you'll have to use translations. The usage of gnIndexableType is described here. You'll find usage informations about translate() method here

Top

Methods

Genese provides many useful methods, like "classic" CRUD operations, but other interesting methods which will help you to translate objects or to map them in the type that you want.

| method | Usage | | -------------- | -------------- | | create() | Sends a POST request to add an object in database. Needs to respect Genese standards. | | createCustom() | Sends a POST request to add an object in database. Possibility to use custom params, without respecting the Genese standards. | | delete() | Sends a DELETE request to remove an object in database. Needs to respect Genese standards. | | deleteCustom() | Sends a DELETE request to remove an object in database. Possibility to use custom params, without respecting the Genese standards. | | fetch() | Sends a fetch request. Useful if you can't use the HttpClient for one or another reason. | | getAll() | Sends a GET request to get a list of objects from database and to format them with the asked type. Needs to respect Genese standards. | | getAllWithPagination() | Sends a GET request to get a list of objects from database and to format them with the asked type. Needs to respect Genese standards. | | getAllCustom() | Sends a GET request to get a list of objects from database and to format them with the asked type. Possibility to use custom params, without respecting the Genese standards. | | getArray() | Sends a GET request to get an array of array of objects from database and to format them with the asked type. | | getOne() | Sends a GET request to get an object from database and to format it with the asked type. Needs to respect Genese standards. | | getOneCustom() | Sends a GET request to get an object from database and to format it with the asked type. Possibility to use custom params, without respecting the Genese standards. | | request() | Sends a http.request() method, which is permitting you to call api not respecting REST conventions, like using a POST for getting objects. | | translate() | Special method used to translate automatically objects which are multi-languages in one of these languages. Needs to respect Genese standards. | | update() | Sends a PUT request to update an object in database. Needs to respect Genese standards. | | updateCustom() | Sends a PUT request to update an object in database. Possibility to use custom params, without respecting the Genese standards. |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@genese/angular

Table of Contents

Why use @genese/angular ?

Installation

1. Config

2. Import Genese module

3. Inject geneseService in your component

Models

Primitives

Nested objects

Indexable types

Translations

Methods

create< T >(newObject: T, options?: RequestOptions): Observable<T | any>

createCustom< T >(path: string, body?: object, options?: RequestOptions): Observable<T | any>

delete< T >(id: string): Observable< ResponseStatus>

deleteCustom< T >(path: string, options?: RequestOptions): Observable< ResponseStatus>

fetch< T >(path: string, method: RequestMethod, requestInit?: RequestInit): Promise< T>

getAll< T >(params?: GetAllParams): Observable< T[]>

getAllCustom< T >(path: string, params?: GetAllParams): Observable<T[]>

getAllWithPagination< T >(path: string, params: GetAllWithPaginationParams): Observable<{results: T[], totalResults: number}>

getArray< ArrayResponse >(): Observable< T[]>

getOne< T >(id: string): Observable< T>

getOneCustom(path: string, params?: GetOneParams): Observable

request< T >(path: string, method: RequestMethod, options?: RequestOptions): Observable<T | any>

translate(data: any, language: string): any

update< T >(id: string, updatedObject: T, options?: RequestOptions): Observable<T | any>

updateCustom< T >(path: string, body?: object, options?: RequestOptions): Observable<T | any>