gem-hunter

4REST

Installation

  npm install 4rest

  yarn add 4rest

Table of Contents

Motivation

Features

Usage / Examples

🧱Basic

1) Create Instance

import forest from "4rest";

const instance = forest.create({ baseURL: "http://localhost:5000" });

2) Create Service

import { instance } from "./forestInstance";
import { UserWithId, User } from "./types";

const userService = instance.createService<UserWithId, User>("user");

3) Use Service

// GET http://localhost:5000/user
async function getUsers() {
  const users: User[] = await (await userService.getAll()).data;
}

// GET http://localhost:5000/user/:id
async function getUserById(id: string) {
  const user: User = await (await userService.getById(id)).data;
}

// DELETE http://localhost:5000/user
async function deleteAllUsers() {
  const usersDeleted: User[] = await (await userService.deleteAll()).data;
}

// DELETE http://localhost:5000/user/:id
async function deleteUserById(id: ObjectId) {
  const userDeleted: User = await (await userService.deleteById(id)).data;
}

// POST http://localhost:5000/user
async function createUser(newUser: User) {
  const userCreated: User = await (await userService.post(newUser)).data;
}

// PATCH http://localhost:5000/user
async function updateUser(partialUser: Partial<User>) {
  const updatedUser: User = await (await userService.patch(partialUser)).data;
}

// PATCH http://localhost:5000/user/:id
async function updateUserById(id: ObjectId, partialUser: Partial<User>) {
  const updatedUser: User = await (await userService.patchById(id, partialUser)).data;
}

// PUT http://localhost:5000/user
async function updateUser(partialUser: Partial<User>) {
  const updatedUser: User = await (await userService.put(partialUser)).data;
}

// PUT http://localhost:5000/user/:id
async function updateUserById(id: ObjectId, partialUser: Partial<User>) {
  const updatedUser: User = await (await userService.putById(id, partialUser)).data;
}

🎨 Extended

1) Create Extended Service

import { ForestService } from "4rest";

import { instance } from "./forestInstance";

export class UserService extends ForestService<UserWithId, User> {
  constructor() {
    super("user", instance, {
      /* service config will go here */
    });
    /* prefix for request url will be "user" */
  }

  public getByName = (name: string) => this.methodsCreator.getByParam<UserWithId, string>({ suffix: "name" })(name);
  public getByNameWithQuery = (name: string) =>
    this.methodsCreator.get<UserWithId>({ route: "name", config: { params: { name } } })();
  public isEmailTaken = (email: string) =>
    this.methodsCreator.getByParam<boolean, string>({ route: ["email", "taken"] })(email);
}

2) Use Extended Service

const userService = new UserService();

async function getUserName(name: string) {
  const user: User = await (await userService.getByName(name)).data;
}

async function getUserNameByQuery(name: string) {
  const user: User = await (await userService.getByNameWithQuery(name)).data;
}

async function isEmailTaken(email: string) {
  const isEmailTaken: boolean = await (await userService.isEmailTaken(email)).data;
}

Configuration

📀 Forest Instance

Instance Creation

import forest from "4rest";

/* Customised Forest Instance can be based on
   AxiosInstance, AxiosRequestConfig */

const forestInstance = forest.create({
    axiosSettings: /* Here goes instance or config*/,
    globalServiceConfig: /* Here goes service configuration that will be applied by default to
                            all created service from these ForestInstance*/
  });

interface InstanceConfig {
  axiosSettings?: AxiosSettings;
  globalServiceConfig?: ServiceConfig;
}

Axios Instance Access

import { forestInstance } from "./instance";

const response = forestInstance.axiosInstance.get("localhost:5000/users" /* Here goes axios config*/);

📀 Forest Service

Configure Service with createService() Method:

1) Methods REST Routes

import { instance } from "./forestInstance";

const userService = instance.createService<User>("user", {
  /* All Service built in CRUD methods route control ( string | string[] ) */
  routes: {
    getAll: ["get", "all"], // GET http://localhost:5000/user/get/all
    deleteAll: "all",       // DELETE http://localhost:5000/user/all
    deleteById: "id",       // DELETE http://localhost:5000/user/id/:id
    ...,
    post: "create",         // POST http://localhost:5000/user/create
    patch: "update"         // PATCH http://localhost:5000/user/update
    patchById: "update"     // PATCH http://localhost:5000/user/update/:id
  }
});

2) Request Config

import { instance } from "./forestInstance";

const userService = instance.createService<UserWithId, User, number>("user", {
  requestConfigByMethod: {
    /* Request Config Per Method */
    getAll: { params: { page: 1, size: 10 } },
    getById: { maxRedirects: 3 },
  },
  requestConfig: {
    /* Request Config For All Methods */
    headers: {
      Authentication: "Bearer Header",
    },
  },
});

3) Payload Data Key

// By Default
request: {
  body: data,
  ...
}

// After Setting payloadKey
request: {
  body: {
    [payloadKey]: data
  },
  ...
}

import { instance } from "./forestInstance";

const userService = instance.createService<UserWithId, User, number>("user", {
  payloadKey: "update",
  payloadKeyByMethod: { post: "data" },
});

4) OnSuccess / OnError Handling

const userService = forestInstance.createService<UserWithId, User, number>("user", {
    onSuccess: (response) => response.data,
    onError: (error) => {
      return { error, msg: "error" };
    },
  });

const userService = forestInstance.createService<UserWithId, User, number>("user", {
    onSuccess: (response, metadata) => {
      console.log(metadata.serviceConfig.validation);
      return response.data
    },
    onError: (error, metadata) => {
      console.log(metadata.serviceConfig.routes);
      return { error, msg: "error" };
    },
  });

const userService = forestInstance.createService<UserWithId, User, number>("user", {
    onSuccessByMethod: {
      getAll: (response) => response.data,
      getById: (response) => response.status,
      ...,
      post: (response, metadata) => {
        console.log(metadata.serviceFunction);

        return response.data;
      },
    },
    onErrorByMethod: {
      getById: (error) => {
        return { error, msg: "errorByMethod" };
      },
      ...,
      post: (error, metadata) => {
        console.log('error at method:', metadata.serviceFunction);

        throw error;
      },
    },
  });

5) Zod Validation

export const UserSchema = z.object({
  name: z.string(),
  email: z.string().optional(),
});

export const UserWithIdSchema = UserSchema.extend({
  _id: z.number(),
});

import { UserWithIdSchema, UserSchema } from "../../types/user";

const userService = forestInstance.createService<UserWithId, User, number>("user", {
  validation: {
      types: { resoponseData: UserWithIdSchema },
    }
  }
});

// Valid Data, no error will be thrown
[{ _id: 1, name: "John Smith" }];

// Invalid data, will throw error
[{ name: "John Smith" }];

import { UserWithIdSchema, UserSchema } from "../../types/user";

const userService = forestInstance.createService<UserWithId, User, number>("user", {
  validation: {
    onMethods: {
      post: { types: { requestPayload: UserSchema, resoponseData: UserWithIdSchema } },
      getById: { types: { resoponseData: UserSchema.strict() } },
    },
  },
});

// Valid Data, no error will be thrown
{ name: "John Smith", email: "john.smith@gmail.com" };

// Invalid data, will throw error
{ email: "john.smith@gmail.com" };

import { UserWithIdSchema, UserSchema } from "../../types/user";

const userService = forestInstance.createService<UserWithId, User, number>("user", {
  validation: {
    onMethods: {
      post: { types: { requestPayload: UserSchema, resoponseData: UserWithIdSchema } },
      getById: { types: { resoponseData: UserSchema.strict() } },
    },
    types: { resoponseData: UserWithIdSchema },
  },
});

📀 Methods Creator Helper

public getByName = (name: string) => this.methodsCreator.getByParam<UserWithId, string>({ suffix: "name" })(name);
public getByNameWithQuery = (name: string) => this.methodsCreator.get<UserWithId>({ route: "name", config: { params: { name } } })();
public isEmailTaken = (email: string) => this.methodsCreator.getByParam<boolean, string>({ route: ["email", "taken"] })(email);

Configuration Options:

Base Helper Method:

interface BaseConfig {
  route?: Route; // string or string[]
  config?: AxiosRequestConfig;
  serviceFunction?: ServiceFunction;
  validation?: MethodValidationConfig; // configuartion object based on Zod Schemas;
  onSuccess?: OnSuccessFunction;
  onError?: OnErrorFunction;
}

Payload Helper Method:

interface PayloadConfig {
  route?: Route;
  config?: AxiosRequestConfig;
  validation?: MethodValidationConfig;
  onSuccess?: OnSuccessFunction;
  onError?: OnErrorFunction;
  key?: Key; // string
}

By Param Helper Method:

interface ByParamConfig {
  route?: Route;
  suffix?: Route; // string or string[] added after the param in request url
  config?: AxiosRequestConfig;
  validation?: MethodValidationConfig;
  onSuccess?: OnSuccessFunction;
  onError?: OnErrorFunction;
}

Payload By Param Helper Method:

interface PayloadByParamConfig {
  route?: Route;
  suffix?: Route;
  config?: AxiosRequestConfig;
  validation?: MethodValidationConfig;
  onSuccess?: OnSuccessFunction;
  onError?: OnErrorFunction;
  key?: Key;
}

Types

Service Generics

class ForestService<ResponseData = any, PayloadData = Response, IdType = string>

import { instance } from "./forestInstance";
import { UserWithId, User } from "./types";

const userService = instance.createService<UserWithId, User, string>("user");

// ResponseData - UserWithId
// PayloadData - User
// IdType - string

getAll

getById

deleteAll

deleteById

post

patch

patchById

put

putById

const data: boolean = await(await userService.post<boolean>(/* newUserData */)).data;

Service Method Metadata

interface Metadata {
  serviceConfig?: ServiceConfig; // current service config
  serviceFunction?: ServiceFunction; // name of one of the built in base service functions
}

OnSuccess Function

type OnSuccessFunction = <T>(value: AxiosResponse<T>, metadata?: Metadata) => any;

OnError Function

type OnSuccessFunction = <T>(value: AxiosResponse<T>, metadata?: Metadata) => any;

Validation

interface ValidationTypes<T = ZodSchema> {
  requestPayload?: T;
  resoponseData?: T;
}

interface MethodsValidation {
  types: ValidationTypes;
}

interface ServiceValidationConfig {
  types: ValidationTypes;
  onMethods?: Partial<Record<ServiceFunction, MethodsValidation>>;
}

type MethodValidationConfig = ValidationTypes;

License