utils
is a package containing useful functions to achieve interplay
between a webcomponent, which extends superclasses, and
either the DOM or the browser.
utils
can be grouped into the following
- i18n
- http client
- href
- url
Provides a connection with browser navigator.language
and translates
the following structure according with the value of navigator.language
:
type LocalizedText = string | Record<string, string>
using the following rules:
- a string as input is turned into itself
- an object with language keys is checked against
navigator.language
first and when not found againstnavigator.language.substring(0, 2)
. If neither is found it looks for'en'
key which is default and otherwise it does a string cast.
There's a function that handles automatically the whole translation resolution called localize
which supports undefined input
const input = 'ciao'
expect(localize(input)).toStrictEqual('ciao')
const input = {}
expect(localize(input)).toStrictEqual('[object Object]')
const input = {'en': 'hi'}
expect(localize(input)).toStrictEqual('hi')
const input = {'en': 'hi', 'it': 'ciao'}
expect(localize(input)).toStrictEqual('hi') // when browser is in anything different from 'it'
expect(localize(input)).toStrictEqual('ciao') // when browser is set to 'it'
to provide the language you could use getLocalizedText
export function getLocalizedText (
localizedText: LocalizedText,
lang: string = navigator.language || 'en'
): string;
finally the browser language is provided by getNavigatorLanguage()
Http Client is a wrapper around browser's fetch
that avoid including third party libraries
when fetching require standard handling (mostly JSON + Text support) and 200, 204, and error handling.
More complex scenarios can be still achieved since this client exposes again the instance of fetch is using.
An http client can be created via
interface HttpClientSupport extends Element {
basePath?: string
headers?: HeadersInit
}
const el = document.createElement('div')
const support: HttpClientSupport = Object.assing(el, {
basePath: '/my-base-path',
headers: {
'Authentication': 'Bearer encodedBearer'
}
})
const httpClient = createFetchHttpClient.call(support)
then httpClient
enjoys the HttpClientInstance
interface
type HttpMethods = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'
type HttpClientConfig = Omit<RequestInit, 'method'> & {
params?: string | Record<string, string> | string[][] | URLSearchParams
inputTransform?: (data: any) => BodyInit | null | undefined
outputTransform?: (body: Body) => Promise<any>
error?: (err: unknown) => Promise<unknown>
raw?: boolean
downloadAsFile?: boolean
}
type GetHandler =
<T = any>(url: string, config?: HttpClientConfig) =>
Promise<HttpClientResponse<T>>
type FetchHandler =
(url: string, config?: HttpClientConfig & {method?: HttpMethods}) =>
Promise<Response>
type PostHandler =
<D = any, T = any>(url: string, data: D, config?: HttpClientConfig) =>
Promise<HttpClientResponse<T>>
type PostMultipartHandler =
<T = any>(url: string, data: FormData, config?: HttpClientConfig) =>
Promise<HttpClientResponse<T>>
export type HttpClientInstance = {
get: GetHandler
post: PostHandler
put: PostHandler
delete: PostHandler
postMultipart: PostMultipartHandler
fetch: FetchHandler
}
Per call configuration can be acheved by tuning the HttpClientConfig
optional
Object to inject query parameters in the URL
Function to parse the body before performing the HTTP request. By
default is set to JSON.stringify
when post
, delete
, or put
are used
Function to parse the response body after receiving an HTTP response. It acts on
browser Response
interface if:
res.ok
istrue
res.status
is different from204
(No Content)
By default, on get
, post
, delete
, put
, or postMultipart
it checks the
Content-Type
header and maps to
text/*
=>res.text()
application/json
=>res.json()
- otherwise =>
res.blob()
Function to call when an error is found. Defaults to a console.error
call.
Raw is a boolean that when true
returns the promise without handling as described above.
Available on get
. Using Content-Disposition
header, performs a browser native download of the response as a file.