duplojs-to

DuploJSTo est un client HTTP qui facilite la communication avec une API DuploJS. Le package intégre aussi un plugin Duplo qui permet de générer une déclaration des enrtés et des sortie de votre back-end.

Sommaire

• Instalation
• Initialisation
• Premier request
• Configuration
• Instance Requestor
• Générer de la déclaration depuis Duplojs
• Enrichire la déclaration

Instalation

npm i @duplojs/to

Initialisation

import DuploTo from "@duplojs/to";

// client http
const duploTo = new DuploTo();

Premier request

const requestor = duploTo.request(
    "/user/{id}",
    {
        method: "GET",
        params: {id: 2},
    }
);
const result = await requestor.result // resultat de la request

const result = await duploTo.patch(
    "/user/{id}/firstname",
    "Mathieu"
    {params: {id: 50}}
)
.result;

const data = await duploTo.get(
    "/users",
    {query: {limit: 20}}
)
.sd();

await duploTo.get(
    "/user/{id}",
    {params: {id: 789}}
)
.info("user.get", (data) => {
    // some action when response holds info 'user.get'
})
.s((data) => {
    // some action when response is successfull
})
.code(200, (data) => {
    // some action when response has status 200
})
.e((data) => {
    // some action when response is wrong
})
.result;

Configuration

const duploTo = new DuploTo({
    prefix: "api", 
    host: "duplo.campani.fr",
    https: true,
});

Config

propriétés|valeur|definition ---|---|--- prefix|string | undefined|Définis un prefix qui sera utilisé pour chacune des request https|boolean | undefined|Si true, Cela utilisera le protocole https. Si false, ce sera le protocole http qui sera utilisé. Dans le cas ou il n'est pas défini, le protocole utilisé sera celui actuelle de la page. host|string | undefined| définis l'host des requests. Exemple : "www.youtube.com", Et si la propriété n'est pas défini, la valeur par défaut, sera l'host de la page actuelle. keyInfo|string | undefined|La clé pour trouver l'info dans les headers. Valeur pars défaut "info".

Propriété de l'instance

propriétés|valeur|definition ---|---|--- request|request(path: string, parameters?: RequestParameters, interceptorParams?: interceptorParameter): Requestor;|Permet de faire une request HTTP. get|get(path: string, parameters?: RequestParameters, interceptorParams?: interceptorParameter): Requestor;|Permet de faire une request GET HTTP. head|head(path: string, parameters?: RequestParameters, interceptorParams?: interceptorParameter): Requestor;|Permet de faire une request HEAD HTTP. options|options(path: string, parameters?: RequestParameters, interceptorParams?: interceptorParameter): Requestor;|Permet de faire une request OPTIONS HTTP. delete|delete(path: string, parameters?: RequestParameters, interceptorParams?: interceptorParameter): Requestor;|Permet de faire une request DELETE HTTP. post|post(path: string, body?: any, parameters?: RequestParameters, interceptorParams?: interceptorParameter): Requestor;|Permet de faire une request POST HTTP. put|put(path: string, body?: any, parameters?: RequestParameters, interceptorParams?: interceptorParameter): Requestor;|Permet de faire une request PUT HTTP. patch|patch(path: string, body?: any, parameters?: RequestParameters, interceptorParams?: interceptorParameter): Requestor;|Permet de faire une request PATCH HTTP. setDefaultHeaders|setDefaultHeaders(headers: Record<string, string \| number \| string[] \| undefined>): this;|Serre a définir des headers qui seront envoyer a chaque request. setRequestInterceptor|setRequestInterceptor(requestInterceptor: (request: RequestObject, params: interceptorParameter) => RequestObject): this;|Définit une fonction qui permet d'intercepter les donner des request. Elle ce lance avand l'envoi de la request. Cela serre a modifer les données ou a pour effectué des action a ce moment la. setResponseInterceptor|setResponseInterceptor(responseInterceptor: (response: ResponseObject, request: RequestObject, params: interceptorParameter) => ResponseObject): this;|Définit une fonction qui permet d'intercepter les donner des réponses. Elle ce lance juste aprés que la request sois terminer et avand le traitement pars le client. Cela serre a modifer les données ou a pour effectué des action a ce moment la. addHookInfo|addHookInfo(info: string, cb: (requestObject: RequestObject, responseObject: ResponseObject) => void): this;|Permet d'ajouter une fonction qui ce lencera quand une request portera l'info passer en premier argument. removeHookInfo|removeHookInfo(info: string, cb: AnyFunction): this;|Permet de retiré une fonction qui a étais utilisé comme hook. addHookCode|addHookCode(code: number, cb: (requestObject: RequestObject, responseObject: ResponseObject) => void): this;|Permet d'ajouter une fonction qui ce lencera quand une request portera le code passer en premier argument. removeHookCode|removeHookCode(code: number, cb: AnyFunction): this;|Permet de retiré une fonction qui a étais utilisé comme hook. addHookError|addHookError(cb: (error: Error) => void): this;|Permet d'ajouter une fonction qui ce lencera quand une request sera en echec. removeHookError|removeHookError(cb: AnyFunction): this;|Permet de retiré une fonction qui a étais utilisé comme hook. enriched|this;|Cette propriéter permet d'accerdé l'instance typé du client.

Exemple configuration

interface InterceptorParams{
    enabledLoader?: boolean
}

const duploTo = new DuploTo<InterceptorParams>();

duploTo.setRequestInterceptor((request, params) => {
    // params === InterceptorParams
    return request;
});

duploTo.setResponseInterceptor((response, request, params) => {
    // params === InterceptorParams
    return response;
});

duploTo.setDefaultHeaders({
    get token(){
        return "my super tokent"
    }
});

duploTo.addHookInfo(
    "user.connect",
    () => {
        // action
    }
)

Instance Requestor

l'objet Requestor est une interface qui permet d'associer des hooks local a une request. Pour obtenir une instance de l'objet il suffit d'utilisé les methods get|head|options|delete|post|patch|put|request d'une instance DuploTo.

const requestor = await duploTo.get(
    "/users",
    {query: {limit: 20}}
)

Propriété de l'instance

propriétés|valeur|definition ---|---|--- s|s(cb: (data: unknown) => void): this;|Assigne une fonction qui ce lencera en cas de réussite (code [200 ; 299]). sd|sd(): Promise<unknown>;|Renvois un promise qui sera résolut en cas de réussite (code [200 ; 299]). Le resulta du promise sera le body de la response. e|e(cb: (data: unknown) => void): this;|Assigne une fonction qui ce lencera en cas d'echec (code [400 ; 599]). ed|ed(): Promise<unknown>;|Renvois un promise qui sera résolut en cas d'echec (code [400 ; 599]). Le resulta du promise sera le body de la response. info|info(info: string, cb: (data: unknown) => void): this;|Assigne une fonction qui ce lencera si la réponse porte l'info passé en premier argument. id|id(info: string): Promise<unknown>;|Renvois un promise qui sera résolut si la réponse porte l'info passé en premier argument. Le resulta du promise sera le body de la response. code|code(code: number, cb: (data: unknown) => void): this;|Assigne une fonction qui ce lencera si la réponse a le status passé en premier argument. cd|cd(code: number): Promise<unknown>;|Renvois un promise qui sera résolut si la réponse a le status passé en premier argument. Le resulta du promise sera le body de la response. then|then(cb: (response: ResponseObjectSuccess) => void): this;|Assigne une fonction qui ce lencera si le serveur renvois une réponse. catch|catch(cb: (error: Error) => void): this;|Assigne une fonction qui ce lencera en cas d'erreur. finally|finally(cb: (response: ResponseObject) => void): this;|Assigne une fonction qui ce lencera quoi qu'il arrive. result|result: Promise<ResponseObject>;|Promise de la réponse.

Exemple request

duploTo.request(
    "/user/{id}",
    {
        method: "GET",
        params: {id: 2},
    }
)
.s((data) => {
    // some action when response is successfull
})
.result;

await duploTo.get(
    "/users",
    {query: {limit: 10}}
)
.info("users.get", () => {
    // some action when response holds info 'users.get'
})
.result;

await duploTo.patch(
    "/user/{id}/firstname",
    "Mathieu",
    {params: {id: 63}}
)
.code(200, () => {
    // some action when response has status 200
})
.result;

const data = await duploTo.put(
    "/user/{id}",
    {
        firstname: "Mathieu",
        lastname: "Campani",
    },
    {
        params: {id: 30},
        headers: {token: "mon super token"}
    }
)
.sd();

Générer de la déclaration depuis Duplojs

Si vous avez une API Duplojs, vous pouvez générer un fichier de déclaration enfain d'enrichire le typage du client DuploTo.

Pour cela, il fit de utiliser le plugin qui fournit du DuploTo de la manier suivante :

import Duplo from "@duplojs/duplojs";
import duploTypeGenerator from "@duplojs/to/plugin";

const duplo = Duplo({
    port: 1506, 
    host: "localhost", 
    environment: "DEV"
});

/* ... */

duplo.use(duploTypeGenerator, {
    outputFile: "EnrichedDuploTo.ts"
});

Puis lancer votre API Duplojs en ajoutent l'argument --generate-types. (vous pouvez aussi utilisé --only-generate pour stopper le serveur avec la génération de la déclaration).

Maintenant importer ce fichier du coter front de votre projet et implémenter le dans DuploTo.

import DuploTo from "@duplojs/to";
import type {EnrichedDuploTo} from "/path/to/EnrichedDuploTo";

interface InterceptorParams {
    // ...
}

export const duploTo = new DuploTo<
    InterceptorParams, 
    EnrichedDuploTo<InterceptorParams>
>({
    // ...
});

duploTo.enriched //This property has all declaration.

Enrichire la déclaration

La fonction extract dans duplo permet de manier explicite, d'indiquer qu'elle champ son présent sur une route. C'est grasse a cela que le plugin de DuploTo arrive a déterminer le type des entrés d'une route.

//ramdom route in api

duplo
.declareRoute("GET", "/user/{id}")
.extract({
    params: {
        id: zod.string(),
    },
    headers: {
        token: zod.string().ignore(), // field is ignore by type generator
    }
})
.handler(({}, res) => {
    res.code(200).info("user.get").send({firstname: "mathieu"});
});

Parcontre si vous shouétais typés les sortie de duplo pour enrichir la déclaration de DuploTo, il va vous faloir utilisé un autre plugins de duplo qui ce nome what-was-sent. Ce plugin serret a créer des contrat explicite des sortie du duplo.

duplo
.declareRoute("GET", "/user/{id}")
.extract({
    // ...
})
.handler(
    ({}, res) => {
        res.code(200).info("user.get").send({firstname: "mathieu"});
    },
    new IHaveSentThis(200, "user.get", zod.object({firstname: zod.string()}))
);