@zeedhi/zeedhi-miragejs

Zeedhi MirageJS

Servidor MirageJS customizável, criado para aplicações Zeedhi Next

Instalação

Para instalar, rode o seguinte comando:

npm install @zeedhi/zeedhi-miragejs

Configuração

Primeiramente, precisamos configurar as rotas do servidor. Elas são configuradas como objetos js que seguem a interface IRouteConfig, que pode ser encontrada ao final da documentação. Existem 3 tipos de rota:

Rota Estática

Para criar uma rota estática, crie um objeto usando a interface IRouteConfig e defina a propriedade route com o nome da rota. Depois, defina a propriedade staticRoute como true:

import { IRouteConfig } from '@zeedhi/zeedhi-miragejs';

const user: IRouteConfig = {
  route: 'users',
  staticRoute: true,
}

Agora precisamos inserir dados nessa rota. Isso é feito na propriedade data, que recebe um array de objetos.

Importante: todo objeto deve ter uma coluna id

import { IRouteConfig } from '@zeedhi/zeedhi-miragejs';

const user: IRouteConfig = {
  route: 'users',
  staticRoute: true,
  data: [
    {
      id: '1',
      first_name: 'Foo',
      email: '[e-mail]',
    },
    {
      id: '2',
      first_name: 'Bar',
      email: '[e-mail]',
    },
    {
      id: '2',
      first_name: 'Baz',
      email: '[e-mail]',
    },
  ],
};

Rota Dinâmica

Rotas dinâmicas permitem criar múltiplos objetos com uma configuração mínima. Para criá-la, defina a propriedade count (o número total de linhas) e a propriedade columns.

Na propriedade columns será feita a configuração das colunas da rota. Ela recebe um dicionário de objetos, em que o nome da coluna é definido pela chave do objeto.

A propriedade type define o tipo de cada coluna, e aceita os seguintes valores: int, string, float e date.

int

Colunas do tipo int serão números inteiros. Devemos utilizar o símbolo %s na propriedade value, e esse símbolo será posteriormente substituído pelo id da linha.

Ex:

{
  id: {
    type: 'int',
    value: '%s',
  }
}
// Resultará em: 1, 2, 3, 4, ...

{
  id: {
    type: 'int',
    value: '100%s',
  }
}
// Resultará em: 1001, 1002, 1003, 1004, ...

string

Colunas do tipo string funcionam de forma semelhante à int, porém aceita strings.

Ex:

{
  first_name: {
    type: 'string',
    value: 'User %s',
  }
}
// Resultará em: User 1, User 2, User 3, User 4, ...

float

Colunas do tipo float serão números aleatórios. É possível definir o número mínimo, máximo e a precisão das casas decimais, utilizando as propriedades min, max e precision, respectivamente

Ex:

{
  salary: {
    type: 'float',
    min: 1000,
    max: 10000,
    precision: 2,
  }
}
// Resultará em: 8067.01, 4126.8, 7665.45, 3099.1, ...

date

Colunas do tipo date irão gerar datas aleatórias no formato YYYY-MM-DD:

Ex:

{
  hire_date: {
    type: 'date',
  }
}
// Resultará em: 2020-12-23, 2017-02-18, 2020-08-11, 2021-09-11, ...

Foreign Key

Uma coluna pode ser definida como sendo uma Foreign Key, basta definir a propriedade foreignKey como true e a propriedade table com o nome da tabela que ela referencia.

Ex:

{
  department_id: {
    type: 'int',
    foreignKey: true,
    table: 'department',
  }
}

Exemplo Completo

O exemplo abaixo ilustra todas as configurações possíveis de uma rota dinâmica.

Obs: será necessário também criar uma rota department para o exemplo funcionar corretamente.

import { IRouteConfig } from '@zeedhi/zeedhi-miragejs';

const user: IRouteConfig = {
  route: 'users',
  exact: false,
  count: 100,
  columns: {
    id: {
      type: 'int',
      value: '%s',
    },
    first_name: {
      type: 'string',
      value: 'User %s',
    },
    department_id: {
      type: 'int',
      foreignKey: true,
      table: 'department',
    },
    salary: {
      type: 'float',
      min: 1000,
      max: 10000,
      precision: 2,
    },
    hire_date: {
      type: 'date',
    },
  },
};

Rota Externa

Rotas externas utilizam de APIs já existentes para criar datasets baseados nelas. Durante a criação do servidor, será realizada uma requisição automática para buscar os dados externos, que serão formatados da forma necessária.

Para criar uma Rota Externa, defina a propriedade externalApi como true, a propriedade apiUrl contendo a URL dos dados externos, e a propriedade dataColumn especificando qual coluna da Response contém os dados. Por exemplo, se a requisição retornar:

{
  "page": 1,
  "total": 500,
  "results": [...]
}

A propriedade dataColumn deve ser definida como results.

A configuração das colunas segue um formato parecido com o das Rotas Dinâmicas. Aqui, devemos utilizar a propriedade location para definir o caminho para os dados dentro do objeto retornado.

Por exemplo, se a requisição retornar os dados no seguinte formato:

{
  "results": [
    {
      "gender": "male",
      "name": {
        "title": "Mr",
        "first": "Bento",
        "last": "Rezende"
      },
      "email": "[e-mail]",
      "login": {
        "uuid": "2d15994b-0f51-4524-ab85-8332eccec216",
      },
    },
  ],
}

Podemos ver que alguns dados estão dentro de objetos. Para formatar esses dados de uma forma aceitável pelo Zeedhi Next, devemos usar a propriedade location para cada coluna:

import { IExternalColumn, IRouteConfig } from '@zeedhi/zeedhi-miragejs';

const user: IRouteConfig<IExternalColumn> = {
  route: 'users',
  externalApi: true,
  apiUrl: 'https://randomuser.me/api/?results=1000&nat=br',
  dataColumn: 'results',
  columns: {
    id: {
      location: ['login', 'uuid'],
    },
    first_name: {
      location: ['name', 'first'],
    },
    last_name: {
      location: ['name', 'last'],
    },
    email: {
      location: ['email'],
    },
    gender: {
      location: ['gender'],
    },
  },
};

/* Resultará em:
[
  {
    id: "2d15994b-0f51-4524-ab85-8332eccec216",
    first_name: "Bento",
    last_name: "Rezende",
    email: "[e-mail]",
    gender: "male"
  }
]
*/

Inicialização do Servidor

O servidor é inicializado pela função makeServer. Essa função recebe por parâmetro um objeto que segue a interface IServerParams:

IServerParams

Nome	Tipo	Descrição
config	IDictionary<IRouteConfig>	Dicionário contendo os objetos de configuração de cada rota criados conforme a seção anterior
endpoint	string	A url base do servidor. Normalmente será utilizado o `Config.endPoint`
logging	boolean | undefined	Define se o servidor deve exibir os logs de cada requisição no console
timing	number | undefined	Configuração de delay de cada requisição. Mude esse valor caso queira testar o desempenho em conexões lentas

No exemplo abaixo, o servidor será criado com as rotas users (estática) e departments (dinâmica). É possível melhorar a legibilidade desse código separando cada rota em um módulo.

Ex:

import { Config, IDictionary } from '@zeedhi/core';
import { makeServer, IRouteConfig } from '@zeedhi/zeedhi-miragejs';

const user: IRouteConfig = {
  route: 'users',
  staticRoute: true,
  data: [
    {
      id: '1',
      first_name: 'Foo',
      email: '[e-mail]',
    },
    {
      id: '2',
      first_name: 'Bar',
      email: '[e-mail]',
    },
    {
      id: '2',
      first_name: 'Baz',
      email: '[e-mail]',
    },
  ],
};

const department: IRouteConfig = {
  route: 'departments',
  count: 20,
  columns: {
    id: {
      type: 'int',
      value: '%s',
    },
    name: {
      type: 'string',
      value: 'Department %s',
    },
  },
};

const serverConfig: IDictionary<IRouteConfig<any>> = {
  user,
  department,
};

/**
 * Mude a propriedade logging para false para remover os logs do console
 */
makeServer({ endpoint: Config.endPoint, config: serverConfig, logging: true });

Configuração Adicional (Axios)

O pacote @zeedhi/zeedhi-core utiliza o axios na versão 0.21.4, o que o torna incompatível com o MirageJS.

Para corrigir esse problema será necessário instalar (ou criar) um custom adapter do axios:

npm install @zeedhi/axios-mirage-adapter

E podemos utilizar esse adapter a partir dos Interceptors:

import { Config, Interceptor } from '@zeedhi/core';
import { makeServer } from '@zeedhi/zeedhi-miragejs';
import serverConfig from '@/server/config';
import adapter from '@zeedhi/axios-mirage-adapter';

Interceptor.addRequestSuccess((config) => ({ ...config, adapter }));

makeServer({ endpoint: Config.endPoint, config: serverConfig });

Interfaces

IRouteConfig<T = IDataColumn>

Nome	Tipo	Descrição
apiUrl	string | undefined	Url da API externa
count	number | undefined	Número de linhas que serão geradas pela rota dinâmica
columns	IDictionary | undefined	Configuração das colunas de rotas dinâmicas ou externas
data	IDictionary[] | undefined	Dados da rota caso ela seja estática
dataColumn	string | undefined	Nome da coluna onde estão os dados da api externa
exact	boolean | undefined	Define se a rota utilizará filtros exatos ou não. Filtros exatos só retornam dados que estejam de acordo com todos os filtros passados, enquanto os não exatos retornam dados que cumpram apenas 1 dos filtros
externalApi	boolean | undefined	Define se a rota usará uma api externa
route	string	Nome da rota
staticRoute	boolean | undefined	Define se a rota é estática

IExternalColumn

Nome	Tipo	Descrição
location	string[]	Array de strings contendo o caminho para uma propriedade dentro do objeto retornado pela API
showOnList	boolean | undefined	Define se a coluna deverá ser retornada junto com os outros dados. Se for false, a coluna servirá apenas como filtro

IDataColumn

Nome	Tipo	Descrição
foreignKey	boolean | undefined	Define se a coluna é chave estrangeira de alguma outra rota
max	number | undefined	Valor máximo retornado caso a coluna seja do tipo float
min	number | undefined	Valor mínimo retornado caso a coluna seja do tipo float
precision	number | undefined	Precisão das casas decimais
showOnList	boolean | undefined	Define se o campo deverá ser retornado pela requisição. Se for false a coluna servirá apenas como filtro
table	string | undefined	Define a tabela referenciada pela coluna caso ela seja foreignKey
type	string	Tipo da coluna
value	string | undefined	Valor da coluna usado pelos os tipos int e string