safrapay-common v1.6.0-beta.4

Purpose

This project has all the common services for mobile and web applications.

Topics

• Purpose
• Topics
• Setting up
• Building the project
• Structure
  • Core
    • Connector
    • Loader
    • Notificator
  • Hooks
    • useService
    • useLoadingState
    • useNotificationState
  • Services
    • execute()
    • useAsHook()
    • Service declaration
• Generator
  • Service
  • Hook

Setting up

• Configure your npm registry

npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false
npm run registry:authenticate

• Install dependencies

npm install

Building the project

npm run build

Structure

Core

Is all logic encapsulated in private services, that is, they are not exported in the package.

Connector

The service responsible for all the http requests. It is a wrapper for the an Axios instance, containing some other logic, such as error handling, loading state and header injection.

Loader

It is a singleton containing the isLoading state, which is an observable. So everytime an http request starts this state is changed to true and when it ends it is changed back to false.

Notificator

It is also a singleton, containing the notification state, which is an observable. So everytime an http request in completed it is updated. It is used for error handling.

Hooks

Basically a hook is a function that can use in our components to encapsulate some logic. For more details about React Hooks read the official documentation. In the hooks folder we have all the custom hooks, through them we can expose some core service.

useService

Is a hook that encapsulate all the logic on using a service into a React component. It basically return an object with the following properties:

• response:
  • A state representing the response coming from the service.
• error:
  • A state representing the error coming from the service, if it occurs.
• send:
  • It`s a function that triggers the service call.
• onSuccess:
  • It`s an event function for success.
  • Receives a handler to be executed when response is returned successfully.
• onError:
  • It`s an event function for error.
  • Receives a handler to be executed when service returns an error.

useLoadingState

It create an isLoading state, based on the global state located on the Loader core service. The isLoading state is automatically updated when Loader global state changes.

useNotificationState

It create an notification state, based on the global state located on the Notificator core service. The notification state is automatically updated when Notificator global state changes.

Services

Each http request in the project is represented by a service, which have both request and response types. The services expose two main methods: execute and useAsHook.

execute()

This method is responsible for execute the http request with the specific configuration.

useAsHook()

This method can be used into React components, as a hook. It basically is the useService hook but with the especific execute logic.

Service declaration

Every service extends the ApiService class, which receives an object that contains the request configuration.

Generator

Execute the command:

npm run generator

It will give us two options:

• Service
• Hook

Service

To generate a service we need the following parameters:

• Domain name:
  • The entity you want the service to be associated with.
• Service name:
  • Must describe the request method.
• Endpoint URL.
• Endpoint method.

It will generate a new directory into the domain directory, with an index.ts file.

import ApiService from '@services/_base';
import GetExampleResponse from './interfaces/response';
import GetExampleRequest from './interfaces/request';

class GetExampleService extends ApiService<
  GetExampleResponse,
  GetExampleRequest
> {
  constructor() {
    super({
      config: request => ({
        url: '/example',
        method: 'GET',
        params: request,
      }),
      handleLoader: true,
      handleError: true,
    });
  }
}

export default GetExampleService;
export { GetExampleResponse, GetExampleRequest };

It also generate two interfaces into an interfaces directory. The request.ts, that represents the request body.

export default interface GetExampleRequest {}

And the response.ts, that represents the response body.

export default interface GetExampleResponse {}

This is our base to define any service.

Hook

To generate a hook we pass only one parameter: The hook name. It must stars with the 'use' prefix.

It will generate a directory for the hook into the hooks folder, with an index.ts.

import * as React from 'react';

const { useState } = React;

export default function useExample() {
  const [state, setState] = useState('');

  return [state, setState];
}

With this base structure you can create your own custom hook.

Both generators automatically export the components.