functional-ts-rest v1.0.9
functional-ts-rest
Introduction
functional-ts-rest
provides a fluent and functional builder for making calls to rest services.
Creating a RestClient
Use the RestClientFactory
to generate a new RestClient
:
import { RestClientFactory } from 'functional-ts-rest';
const restClient : IRestClient<ErrorResponse> = RestClientFactory.create();
Add a bearer auth token using the withBearer
function:
import { RestClientFactory } from 'functional-ts-rest';
const restClient : IRestClient<ErrorResponse> =
RestClientFactory
.withBearer('YourToken')
.create();
You can defined a custom failure type for requests made with the rest client using the withFailure
function. Use this function to map an ErrorResponse to your custom error type:
import { RestClientFactory } from 'functional-ts-rest';
var restClient : IRestClient<string> =
RestClientFactory
.withFailure(error => `Error: ${error.match(response => response.status.toString(), ex => ex.message)}`)
.create();
Using the RestClient
Use the get, post, put and delete functions to build a request and then use the as
function to execute the request and parse the response to your model:
const result =
await restClient
.getAsync(`some/url`)
.withParameters({
textParam: "SomeValue",
numberParam: 100
})
.acceptJson()
.as<MyModel>();
Request Types
The rest client currently supports making GET
, POST
, PUT
, and DELETE
requests:
const result =
await restClient
.getAsync(`some/url`)
.as<MyModel>();
const result =
await restClient
.postAsync(`some/url`)
.asUnit();
const result =
await restClient
.putAsync(`some/url`)
.asUnit();
const result =
await restClient
.deleteAsync(`some/url`)
.asUnit();
Building Requests
withParameter
Adds a parameter to the url of the request.
var result = await restClient
.getAsync(`${api}/test/GetWithTestParameter`)
.withParameter("testParam", "SomeValue")
.acceptJson()
.asUnit();
withParameters
Adds parameters to the url of the request from an input object.
var result = await restClient
.getAsync(`${api}/test/GetWithTestParameters`)
.withParameters({
testParam: "SomeValue",
otherParam: "OtherValue"
})
.acceptJson()
.asUnit();
withHeader
Adds a header to the request.
var result = await restClient
.postAsync(`${api}/test/PostWithHeader`)
.withHeader('SomeHeader', 'SomeValue')
.acceptJson()
.asUnit();
withHeaders
Adds headers to the request from an input object.
var result = await restClient
.postAsync(`${api}/test/PostWithHeaders`)
.withHeaders({
SomeHeader: 'SomeValue',
OtherHeader: 'OtherValue'
})
.asUnit();
withBearer
Adds a function for generating authentication bearer tokens for the request.
var result = await RestClientFactory
.withBearer(() => 'SomeToken')
.create()
.postAsync(`${api}/test/PostWithBearerToken`)
.asUnit();
withBearerAsync
Adds an async function for generating authentication bearer tokens for the request.
var result = await RestClientFactory
.withBearerAsync(async () => 'SomeToken')
.create()
.postAsync(`${api}/test/PostWithBearerToken`)
.asUnit();
withJson
Adds a json body to the request.
var result = await restClient
.postAsync(`${api}/test/PostWithJsonBody`)
.withJson({
userId: 1,
id: 1,
title: "delectus aut autem",
completed: true
})
.asUnit();
withFormData
Adds form data to the request.
var result = await restClient
.postAsync(`${api}/test/PostWithFormData`)
.withFormData({
userId: "1",
id: "1",
title: "delectus aut autem",
completed: "true"
})
.asUnit();
withFormDataUrlEncoded
Adds url encoded form data to the request.
var result = await restClient
.postAsync(`${api}/test/PostWithFormData`)
.withFormDataUrlEncoded({
userId: "1",
id: "1",
title: "delectus aut autem",
completed: "true"
})
.asUnit();
with
Maps the request properties to a new set of request properties. Use this method when you wish to alter the request in a way that no other methods on the builder support.
var result = await restClient
.postAsync(`${api}/test/PostWithHeader`)
.with(request => ({ ...request, headers: { SomeHeader : "SomeValue" } }))
.acceptJson()
.asUnit();
Executing Requests
asResponse
Executes the request and returns a result with the successful response or failure value.
var result : ResultPromise<Response, ErrorResponse> = await restClient
.create()
.postAsync(`${api}/test/PostReturnJsonModel`)
.acceptJson()
.asResponse();
asResponse
Executes the request and parses a successful result to the specified model.
var result : ResultPromise<MyModel, ErrorResponse> = await restClient
.create()
.postAsync(`${api}/test/PostReturnJsonModel`)
.acceptJson()
.as<MyModel>();
asUnit
Executes the request and returns a successful Unit
or a failure value.
var result : ResultPromise<Unit, ErrorResponse> = await restClient
.create()
.postAsync(`${api}/test/PostReturnJsonModel`)
.acceptJson()
.asUnit();
asHtml
Executes the request and parses a successful result to a string of html.
var result : ResultPromise<string, ErrorResponse> = await restClient
.create()
.postAsync(`${api}/test/PostReturnJsonModel`)
.acceptJson()
.asHtml();
asText
Executes the request and parses a successful result to a string.
var result : ResultPromise<string, ErrorResponse> = await restClient
.create()
.postAsync(`${api}/test/PostReturnJsonModel`)
.acceptJson()
.asText();
asBlob
Executes the request and parses a successful result to a Blob.
var result : ResultPromise<Blob, ErrorResponse> = await restClient
.create()
.postAsync(`${api}/test/PostReturnJsonModel`)
.acceptJson()
.asBlob();
Mapping Failures
The RestClient or RestClientFactory can be configured to map error responses to some other error model. The functions available for this are:
withFailure
const restClient : IRestClient<string> =
RestClientFactory
.withFailure(error => `SomeError ${error.match(response => response.status.toString(), ex => ex.message)}`)
.create();
withFailureAsync
const restClient : IRestClient<string> =
RestClientFactory
.withFailureAsync(async error => `SomeError ${await error.matchAsync(response => response.text(), ex => ex.message)}`)
.create();