Skip to content

Latest commit

 

History

History
476 lines (357 loc) · 9.05 KB

Examples.md

File metadata and controls

476 lines (357 loc) · 9.05 KB

Examples

If you are still not sure about how to use Manta Style, you might want to check out Quick Start.

Contents

Mock Simple Data Structure

Access /getUserInfo to get mock user info, the response JSON contains userid, userName, gender.

Packages needed

Builder: @manta-style/builder-typescript or @manta-style/builder-flowtype

Config File

type UserInfo = {
  userid: number;
  userName: string;
  gender: 'male' | 'female';
};
export type GET = {
  '/getUserInfo': UserInfo;
};

Result

{
  "userid": 6.427734778350991,
  "userName": "This is a string message. Customize it mock plugins. (https://github.com/Cryrivers/manta-style/blob/master/documentation/Plugins.md)",
  "gender": "male"
}

Customize each field

Previous example can generate the data structure we want. However, some fields look not very realistic. For example, userid is supposed to a big integer instead of a decimal. userName should look like an internet username. So this example we will make our /getUserInfo generates more realistic data with the help of plugins

Packages needed

Builder: @manta-style/builder-typescript or @manta-style/builder-flowtype

Mock: @manta-style/mock-faker

Config File

type UserInfo = {
  /**
   * @range 10000 99999
   */
  userid: number;
  /**
   * @faker {{internet.userName}}
   */
  userName: string;
  gender: 'male' | 'female';
};
export type GET = {
  '/getUserInfo': UserInfo;
};

Result

{
  "userid": 84162,
  "userName": "Milan_OConner15",
  "gender": "male"
}

Mock an array of some data structure

A new endpoint /getUserInfoList is added, which returns UserInfo of muliple users.

Packages needed

Builder: @manta-style/builder-typescript or @manta-style/builder-flowtype

Mock: @manta-style/mock-faker

Config File

type UserInfo = {
  /**
   * @range 10000 99999
   */
  userid: number;
  /**
   * @faker {{internet.userName}}
   */
  userName: string;
  gender: 'male' | 'female';
};
export type GET = {
  '/getUserInfoList': UserInfo[];
};

Result

[
  {
    "userid": 16935,
    "userName": "Hailee_Cremin",
    "gender": "female"
  },
  {
    "userid": 12459,
    "userName": "Westley.Carter22",
    "gender": "male"
  },
  {
    "userid": 39348,
    "userName": "Michel.Powlowski",
    "gender": "male"
  },
  {
    "userid": 63937,
    "userName": "Salvador56",
    "gender": "male"
  }
]

Mock Success and Failure Response

In practice, an API endpoint does not always return a payload without error. So we also need to support to mock both success and failure conditions.

Packages needed

Builder: @manta-style/builder-typescript or @manta-style/builder-flowtype

Mock: @manta-style/mock-faker

Config File

type UserInfo = {
  /**
   * @range 10000 99999
   */
  userid: number;
  /**
   * @faker {{internet.userName}}
   */
  userName: string;
  gender: 'male' | 'female';
};
type ResponseSuccess<T> = {
  status: 'ok';
  data: T;
};
type ResponseFailure = {
  status: 'error';
  /**
   * @example Not Authorized
   */
  message: string;
};
type Response<T> = ResponseSuccess<T> | ResponseFailure;
export type GET = {
  '/getUserInfo': Response<UserInfo>;
};

Result

Manta Style outputs the success or failure response and changes when you request it. To get a fixed result, simply press S to generate a snapshot.

{
  "status": "ok",
  "data": {
    "userid": 56856,
    "userName": "Whitney2",
    "gender": "male"
  }
}
{
  "status": "error",
  "message": "Not Authorized"
}

Use Custom Types

You can create your own types and share it on npm, and can also import types from communities. In this example, we will have an API endpoint /iwantcats, which outputs a URL to cat images on Unsplash by utilizing the custom type Unsplash built in @manta-style/helpers.

Packages needed

Builder: @manta-style/builder-typescript or @manta-style/builder-flowtype

Mock: (None)

Package: @manta-style/helpers

Config File

Import @manta-style/helpers:

  • TypeScript
import { Unsplash } from '@manta-style/helpers';
  • Flow
import type { Unsplash } from '@manta-style/helpers';

export type GET = {
  '/iwantcats': {
    url: Unsplash<'cats', 1600, 900>;
  };
};

Result

{
  "url": "https://source.unsplash.com/1600x900/?cats"
}

Conditional Types

This example supports TypeScript only

Sometimes there are some constraints among several fields. Say we need to have a /names API, which populates some names and an adjective to describe them. And we assume wgao19 is brilliant, tanhauhau is handsome, jennieji is awesome and cryrivers is dumb.

Packages needed

Builder: @manta-style/builder-typescript

Mock: (None)

Config File

/**
 * @example wgao19
 * @example tanhauhau
 * @example jennieji
 * @example cryrivers
 */
type Name = string;

type AdjectiveForPerson<T> = T extends 'wgao19'
  ? 'brilliant'
  : T extends 'tanhauhau'
    ? 'handsome'
    : T extends 'jennieji' ? 'awesome' : 'dumb';

type Response<T> = {
  name: T;
  adjective: AdjectiveForPerson<T>;
};

export type GET = {
  '/names': Response<Name>;
};

Result

It randomly generates one of following 4 responses. The adjective will always match the name.

{
  "name": "wgao19",
  "adjective": "brilliant"
}
{
  "name": "tanhauhau",
  "adjective": "handsome"
}
{
  "name": "jennieji",
  "adjective": "awesome"
}
{
  "name": "cryrivers",
  "adjective": "dumb"
}

Read information from URL (Basic)

Sometimes we might be interested in information in URLs. URL queries for example, say we have a request /test?country=Singapore, we want to read the country as a Type. Another example is URL params, say we have a request /todo/1, we want to read the id 1.

Packages needed

Builder: @manta-style/builder-typescript or @manta-style/builder-flowtype

Mock: (None)

Package: @manta-style/helpers

Config File

Import @manta-style/helpers:

  • TypeScript
import { Query, Param } from '@manta-style/helpers';
  • Flow
import type { Query, Param } from '@manta-style/helpers';

type Country = Query<'country'>;
type TodoId = Param<'id'>;

export type GET = {
  '/test': { country: Country };
  '/todo/:id': { id: TodoId };
};

Result

Result for URL /test?country=Singapore

{
  "country": "Singapore"
}

Result for URL /todo/1

{
  "id": "1"
}

Read information from URL (Advanced)

This example supports TypeScript only

Since we read information from URL as TypeScript types, not only do they support to display, but also support conditional types.

Back to our /getUserInfo example, say we need to have an upgraded /getInfo endpoint, which gets a UserInfo given URL queries type=user&userid={userid} or gets a GroupInfo given URL queries type=group&groupid={groupid}.

Packages needed

Builder: @manta-style/builder-typescript

Mock: @manta-style/mock-faker

Package: @manta-style/helpers

Config File

import { Query } from '@manta-style/helpers';

type Type = Query<'type'>;
type UserId = Query<'userid'>;
type GroupId = Query<'groupid'>;

type UserInfo<UID> = {
  userid: UID;
  /**
   * @faker {{internet.userName}}
   */
  userName: string;
  gender: 'male' | 'female';
};

type GroupInfo<GID> = {
  groupid: GID;
  /**
   * @faker {{commerce.productAdjective}} {{commerce.productName}}
   */
  groupName: string;
  /**
   * @faker {{address.streetAddress}}, {{address.zipCode}}
   */
  address: string;
};

export type GET = {
  '/getUserInfo': Type extends 'user' ? UserInfo<UserId> : GroupInfo<GroupId>;
};

Result

Access /getUserInfo?type=user&userid=12345:

{
  "userid": "12345",
  "userName": "Cletus79",
  "gender": "female"
}

Access /getUserInfo?type=group&groupid=10086:

{
  "groupid": "10086",
  "groupName": "Handmade Ergonomic Cotton Bike",
  "address": "3202 Fabian Turnpike, 67924"
}

As you can see, the data type it returns respects the conditional type and what user inputs from URL queries.

Proxy to real servers

Packages needed

Builder: @manta-style/builder-typescript or @manta-style/builder-flowtype

Mock: (None)

Package: (None)

Config File

export type GET = {
  /**
   * @proxy https://jsonplaceholder.typicode.com
   */
  '/todos/1': { message: 'This is from Manta Style' };
  /**
   * @proxy https://www.google.com
   */
  '/errorExample': { haha: number };
};

Result