jin-frame

HTTP Reqest = TypeScript Class

A reusable, declarative, type-safe, and extendable HTTP request library.

Why jin-frame?

1. Declarative API Definition
2. Type Safety
3. Support for Retry, Hooks, File Upload, Timeout and Mocking
4. Build upon the Axios Ecosystem
5. Path Parameter Support

Table of Contents

• Comparison of direct usage and jin-frame
• Install
• Usage
• Retry, Timeout
• Authorization
• Requirements
  • Decorator
  • Axios version
• Example
• License

Comparison of direct usage and jin-frame

| Direct usage | Jin-Frame | | ----------------------------------- | ------------------------------------------ | | | | | axios svg | jin-frame svg |

Install

npm install jin-frame --save

yarn add jin-frame --save

pnpm add jin-frame --save

Usage

This is simple example of pokeapi.co.

import { Get, Param, Query, JinFrame } from 'jin-frame';
import { randomUUID } from 'node:crypto';

@Get({ 
  host: 'https://pokeapi.co',
  path: '/api/v2/pokemon/:name',
})
export class PokemonFrame extends JinFrame {
  @Param()
  declare public readonly name: string;

  @Query()
  declare public readonly tid: string;
}

(async () => {
  const frame = PokemonFrame.of({ 
    name: 'pikachu', 
    tid: randomUUID(),
  });
  const reply = await frame.execute();
  
  // Show Pikachu Data
  console.log(reply.data);
})();

Retry, Timeout

Retry and Timeout can be easily applied without installing additional packages.

import { Param, Query, Retry, Timeout, JinFrame } from 'jin-frame';

@Timeout(2000) // Timeout after 2000ms
@Retry({ max: 5, interval: 1000 }) // Retry up to 5 times with 1000ms interval
@Get({ 
  host: 'https://pokeapi.co',
  path: '/api/v2/pokemon/:name',
})
export class PokemonFrame extends JinFrame {
  @Param()
  declare public readonly name: string;

  @Query()
  declare public readonly tid: string;
}

Authorization

import { Get, Param, Query } from 'jin-frame';

@Get({ 
  host: 'https://pokeapi.co'
  path: '/api/v2/pokemon/:name'
  authorization: process.env.YOUR_KEY_HERE
})
export class PokemonFrame extends JinFrame {
  @Param()
  declare public readonly name: string;

  @Query()
  declare public readonly tid: string;
}

Requirements

Decorator

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

{
  "extends": "@tsconfig/node20/tsconfig.json",
  "compilerOptions": {
    // enable experimentalDecorators, emitDecoratorMetadata for using decorator
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
  },
}

Axios version

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

Example

You can find more examples in examples directory.

License

This software is licensed under the MIT.