jin-frame

HTTP Reqest = TypeScript Class

jin-frame help to make HTTP Request template using by TypeScript class, decorator.

Why jin-frame?

1. decorator: decorator function make HTTP request parameter
2. Static Type Checking: Compile-Time static type checking on request parameter
3. HTTP Request can extends inheritance, OOP design
4. Use Axios EcoSystem

Table of Contents

• How to works?
• Comparison of direct usage and jin-frame
• Install
• Useage
• Requirements
• Axios version
• Mocking
• Form
  • application/x-www-form-urlencoded
  • multipart/form-data
• Hook
  • Field for logging, debugging
• Example
• License

How to works?

Comparison of direct usage and jin-frame

| Direct usage | Jin-Frame | | -------------------------------- | --------------------------------------- | | | |

Install

npm i jin-frame --save

Useage

Querystring made by query, Q decorator.

class IamReqest extends JinFrame {
  @JinFrame.Q()
  public readonly name!: string;
}

Path parameter made by param, P decorator and URI.

class IamReqest extends JinFrame {
  // decorator
  @JinFrame.P()
  public readonly id!: string;

  constructor(args: OmitConstructorType<IamReqest, JinBuiltInMember>) {
    // `:` character make path parameter on URI
    super({ ...args, host: 'http://some.api.google.com/jinframe/:id', method: 'post' });
  }
}

Header parameter made by header, H decorator and URI.

class IamReqest extends JinFrame {
  @JinFrame.H({ replaceAt: 'api-key' })
  public readonly apiKey!: string;
}

Body parameter made by body, B decorator and URI.

class IamReqest extends JinFrame {
  @JinFrame.B({ replaceAt: 'api-key' })
  public readonly gene!: string;
}

This is example of union param, body, header parameter.

class TestPostFrame extends JinFrame {
  @JinFrame.param()
  public readonly id!: number;

  @JinFrame.body({ replaceAt: 'test.hello.marvel.name' })
  public readonly name!: string;

  @JinFrame.header({ replaceAt: 'test.hello.marvel.skill' })
  public readonly skill!: string;

  // automatically initialize via base class, have to use same name of args and JinFrame class
  // execute `Object.keys(args).forEach(key => this[key] = args[key])`
  constructor(args: OmitConstructorType<TestPostFrame, JinBuiltInMember>) {
    super({ ...args, $$host: 'http://some.api.yanolja.com/jinframe/:id', $$method: 'POST' });
  }
}

TestPostFrame class create AxiosRequestConfig object below. $$ character is show that is built-in variable.

const frame = new TestPostFrame({ id: 1, name: 'ironman', skill: 'beam' });
console.log(frame.request());

// console.log show below,
{
  timeout: 2000,
  headers: { test: { hello: { marvel: { skill: 'beam' } } }, 'Content-Type': 'application/json' },
  method: 'POST',
  data: { test: { hello: { marvel: { name: 'ironman', gender: 'male' } } } },
  transformRequest: undefined,
  url: 'http://some.api.yanolja.com/jinframe/1',
  validateStatus: () => true
}

You can direct execute jin-frame. Curried request function create after execute it. jin-frame using axios library so using on browser.

const frame = new TestPostFrame({ id: 1, name: 'ironman', skill: 'beam' });
const res = await frame.execute();

// or
const resp = await axios.request(frame.request());

Requirements

1. TypeScript
2. Decorator
   • enable experimentalDecorators, emitDecoratorMetadata option in tsconfig.json

Axios version

| jin-frame | axios | | --------- | --------- | | 2.x | <= 0.27.x | | 3.x | >= 1.1.x |

Mocking

jin-frame use axios internally. So you can use axios-mock-adapter.

import axios from 'axios';
import MockAdapter from 'axios-mock-adpater';

// This sets the mock adapter on the default instance
const mock = new MockAdapter(axios);

// Mock any GET request to /users
// arguments for reply are (status, data, headers)
mock.onGet('/users').reply(200, {
  users: [{ id: 1, name: 'John Smith' }],
});

const frame = new UserFrame({ params: { searchText: 'John' } });
const reply = await frame.execute();

console.log(response.data);

Form

The form data is multipart/form-data and application/x-www-form-urlencoded. Use to upload files or submit form fields data.

application/x-www-form-urlencoded

application/x-www-form-urlencoded converts from data using the trasformRequest function in axios. For jin-frame, if you set the application/x-www-form-urlencoded to content-type, use the built-in transformRequest function or pass transformRequest function to constructor.

multipart/form-data

jin-frame uses the form-data package for form-data processing. If you set the multipart/form-data content-type, use the form-data package to generate the AxiosRequestConfig data field value. Alternatively, upload the file by passing the customBody constructor parameter.

Hook

JinFrame support pre, post hook side of each request.

class TestPostFrame extends JinFrame {
  @JinFrame.param()
  public readonly id!: number;

  @JinFrame.body({ replaceAt: 'test.hello.marvel.name' })
  public readonly name!: string;

  @JinFrame.header({ replaceAt: 'test.hello.marvel.skill' })
  public readonly skill!: string;

  override preHook(req: AxiosRequestConfig<unknown>): void {
    console.log('pre hook executed');
  }

  override postHook(req: AxiosRequestConfig<unknown>): void {
    console.log('post hook executed');
  }

  // automatically initialize via base class, have to use same name of args and JinFrame class
  // execute `Object.keys(args).forEach(key => this[key] = args[key])`
  constructor(args: OmitConstructorType<TestPostFrame, JinBuiltInMember>) {
    super({ ...args, host: 'http://some.api.google.com/jinframe/:id', method: 'POST' });
  }
}

const frame = new TestPostFrame({ id: 1, name: 'ironman', skill: 'beam' });

// 'pre hook executed' display console
const res = await frame.execute();
// 'post hook executed' display console

Field for logging, debugging

query, header, param, body getter function have each request parameter.

const frame = new TestPostFrame({ id: 1, name: 'ironman', skill: 'beam' });
// jin-frame build body, header, query, param variable
const res = await frame.execute();

// You can verify body, header, query parameter
console.log(frame.body);
console.log(frame.header);
console.log(frame.query);
console.log(frame.param);

Example

You can find more examples in examples directory.

License

This software is licensed under the MIT.