gustavoguichard / make-service

make-service A type-safe thin wrapper around the API to better interact with external APIs. It adds a set of little features and allows you to parse responses with standard-schema libraries. Features • 🤩 Type-safe return of and . Defaults to instead of . • 🚦 Easily setup an API with a and common options like for every request. • 🏗️ Compose URL from the base by just calling the endpoints and an object-like . • 🐾 Replaces URL wildcards with a **strongly-typed** object of . • 🧙‍♀️ Automatically stringifies the of a request so you can give it a JSON-like structure. • 🐛 Accepts a function for debugging. • 🔥 It can transform responses and payloads back and forth to (e.g.) support interchangeability of casing styles (kebab-case -> camelCase -> snake_case -> kebab-case). Example Table of Contents • Installation • API • makeService • Type-checking the response body • Runtime type-checking and parsing the response body • Dealing with parsing errors • Supported HTTP Verbs • Headers • Passing a function as • Deleting a previously set header • Base URL • Transformers • Request transformers • Response transformers • Body • Query • Params • Trace • makeFetcher • enhancedFetch • typedResponse • Transform the payload • Other available primitives • addQueryToURL • ensureStringBody • makeGetApiURL • mergeHeaders • replaceURLParams • Contributors • Acknowledgements Installation Or you can use it with Deno: API This library exports the function and some primitives used to build it. You can use the primitives as you wish but the will have all the features combined. makeService The main function of this lib is built on top of the primitives described in the following sections. It allows you to create a service object with a and common options like for every request. This service object can be called with every HTTP method and it will return a . On the example above, the request will be sent with the following arguments: Type-checking the response body The object returned by the can be type-casted with a given generic type. This will type-check the and methods. Runtime type-checking and parsing the response body Its can also be parsed with a standard schema parser. Here follows a little more complex example with Zod: You can transform any in a like that by using the function. Dealing with parsing errors If the response body does not match the given schema, it will throw a **ParseResponseError** which will have a message carrying all the parsing issues and its messages. You can catch it to inspect the issues: Supported HTTP Verbs Other than the it also accepts more HTTP verbs: Headers The argument can be a object, a , or an array of tuples (entries). The option on and the argument will be merged together, with the argument taking precedence. Passing a function as The option on can be a sync or async function that will run in every request before it gets merged with the other headers. This is particularly useful when you need to send a refreshed token or add a timestamp to the request. Deleting a previously set header In case you want to delete a header previously set you can pass or as its value: Note: Don't forget headers are case insensitive. All the features above are done by using the function internally. Base URL The service function can receive a or as base and it will be able to merge them correctly with the given path: You can use the method to do that kind of URL composition. Transformers can also receive and as options that will be applied to all requests. Request transformers You can transform the request in any way you want passing a transformer function as a parameter. This will be applied to all requests for that service. A useful example is to implement a global request timeout for all endpoints of a service: Please note that the option will be applied _after_ the request transformer runs. If you're using a request transformer, we recommend adding custom headers inside your transformer instead of using both options. Response transformers You can also transform the response in any way you want, like: Body The function can also receive a object that will be stringified and sent as the request body: You can also pass any other accepted values as body, such as , , , , , etc. This is achieved by using the function internally. Query The service can also receive an object that can be a , a , or an array of entries and it'll add that to the path as queryString: This is achieved by using the function internally. Params The function can also receive a object that will be used to replace the wildcards in the path: The object will not type-check if the given object doesn't follow the path structure. This is achieved by using the function internally. Trace The function can also receive a function that will be called with the final and arguments. Therefore you can know what are the actual arguments that will be passed to the API. makeFetcher This method is the same as but it doesn't expose the HTTP methods as properties of the returned object. This is good for when you want to have a service setup but don't know the methods you'll be calling in advance, like in a proxy. Other than having to pass the method in the this is going to have all the features of . enhancedFetch A wrapper around the service. It returns a instead of a . This function accepts the same arguments as the API - with exception of JSON-like body -, and it also accepts an object of to replace URL wildcards, an object-like , and a function. Those are all described above in . This slightly different is typed as . The function can also return a in order to send traces to an external service or database. typedResponse A type-safe wrapper around the object. It adds a and method that will parse the response with a given standard schema library. If you don't provide a schema, it will return instead of , then you can also give it a generic to type cast the result. Transform the payload The combinat…