@alwatr/fetch
Version:
Enhanced fetch API with cache strategy, retry pattern, timeout, helper methods and enhanced types.
8 lines (7 loc) • 16.6 kB
Source Map (JSON)
{
"version": 3,
"sources": ["../src/main.ts", "../src/core.ts"],
"sourcesContent": ["import {HttpStatusCodes, type HttpStatusCode} from '@alwatr/http-primer';\n\nimport {handleCacheStrategy_, logger_, processOptions_, cacheSupported} from './core.js';\n\nimport type {FetchOptions, ResponseError, ResponseSuccess} from './type.js';\n\nexport {cacheSupported};\nexport type * from './type.js';\n\n/**\n * It's a wrapper around the browser's `fetch` function that adds retry pattern, timeout, cacheStrategy,\n * remove duplicates, etc.\n *\n * @see {@link FetchOptions}\n * @see {@link ResponseSuccess}\n * @see {@link ResponseError}\n *\n * @param options Fetch options.\n *\n * @returns A success or error response.\n *\n * @example\n * ```typescript\n * const responseJson = await fetchJson({\n * url: '/api/products',\n * queryParameters: {limit: 10},\n * timeout: 8_000,\n * retry: 3,\n * cacheStrategy: 'stale_while_revalidate',\n * cacheDuplicate: 'auto',\n * });\n * ```\n */\nexport async function fetchJson<T extends JsonObject>(options: FetchOptions): Promise<T | ResponseError> {\n let response;\n let responseText;\n let responseJson;\n\n try {\n response = await fetch(options);\n responseText = await response.text();\n responseJson = JSON.parse(responseText) as (ResponseError | ResponseSuccess<T>);\n if (responseJson.ok === false) {\n throw new Error(`fetch_response_nok`);\n }\n // responseJson.statusCode ??= response.status as HttpStatusCode;\n return responseJson;\n }\n catch (error) {\n const responseError: ResponseError = {\n ...responseJson,\n ok: false,\n statusCode: (response?.status as HttpStatusCode) ?? HttpStatusCodes.Error_Server_500_Internal_Server_Error,\n errorCode: (responseJson?.errorCode as string) ?? (error as Error).message,\n errorMessage: (responseJson?.errorMessage as string) ?? (error as Error).message,\n // responseText,\n };\n\n logger_.accident('fetchJson', 'fetch_json_failed', {responseError, error, responseText});\n return responseError;\n }\n}\n\n/**\n * It's a wrapper around the browser's `fetch` function that adds retry pattern, timeout, cacheStrategy,\n * remove duplicates, etc.\n *\n * @see {@link FetchOptions}\n *\n * @param options Fetch options.\n *\n * @returns A promise that resolves to the Response to that request, whether it is successful or not.\n *\n * @example\n * ```typescript\n * const response = await fetch({\n * url: '/api/products',\n * queryParameters: {limit: 10},\n * timeout: 8_000,\n * retry: 3,\n * cacheStrategy: 'stale_while_revalidate',\n * cacheDuplicate: 'auto',\n * });\n * ```\n */\nexport function fetch(options: FetchOptions): Promise<Response> {\n options = processOptions_(options);\n logger_.logMethodArgs?.('fetch', {options});\n return handleCacheStrategy_(options as Required<FetchOptions>);\n}\n", "import {delay} from '@alwatr/delay';\nimport {getGlobalThis} from '@alwatr/global-this';\nimport {HttpStatusCodes, MimeTypes} from '@alwatr/http-primer';\nimport {createLogger} from '@alwatr/logger';\nimport {packageTracer} from '@alwatr/package-tracer';\nimport {parseDuration} from '@alwatr/parse-duration';\n\nimport type {FetchOptions} from './type.js';\n\n__dev_mode__: packageTracer.add(__package_name__, __package_version__);\n\nexport const logger_ = /* #__PURE__ */ createLogger('@alwatr/fetch');\n\nconst globalThis_ = /* #__PURE__ */ getGlobalThis();\n\nlet cacheStorage_: Cache;\nexport const cacheSupported = /* #__PURE__ */ Object.hasOwn(globalThis_, 'caches');\n\nconst duplicateRequestStorage_: Record<string, Promise<Response>> = {};\n\n/**\n * Process fetch options and set defaults, etc.\n *\n * @param options Fetch options.\n *\n * @returns Required fetch options.\n */\nexport function processOptions_(options: FetchOptions): Required<FetchOptions> {\n options.method ??= 'GET';\n options.window ??= null;\n\n options.timeout ??= 8_000;\n options.retry ??= 3;\n options.retryDelay ??= 1_000;\n options.cacheStrategy ??= 'network_only';\n options.removeDuplicate ??= 'never';\n options.headers ??= {};\n\n if (options.cacheStrategy !== 'network_only' && cacheSupported !== true) {\n logger_.incident?.('fetch', 'fetch_cache_strategy_unsupported', {\n cacheSupported,\n });\n options.cacheStrategy = 'network_only';\n }\n\n if (options.removeDuplicate === 'auto') {\n options.removeDuplicate = cacheSupported ? 'until_load' : 'always';\n }\n\n if (options.url.lastIndexOf('?') === -1 && options.queryParams != null) {\n const queryParams = options.queryParams;\n // prettier-ignore\n const queryArray = Object\n .keys(queryParams)\n .map((key) => `${key}=${String(queryParams[key])}`);\n\n if (queryArray.length > 0) {\n options.url += '?' + queryArray.join('&');\n }\n }\n\n if (options.bodyJson !== undefined) {\n options.body = JSON.stringify(options.bodyJson);\n options.headers['content-type'] = MimeTypes.JSON;\n }\n\n if (options.bearerToken !== undefined) {\n options.headers.authorization = `Bearer ${options.bearerToken}`;\n }\n else if (options.alwatrAuth !== undefined) {\n options.headers.authorization = `Alwatr ${options.alwatrAuth.userId}:${options.alwatrAuth.userToken}`;\n }\n\n return options as Required<FetchOptions>;\n}\n\n/**\n * Handle Cache Strategy over `handleRemoveDuplicate_`.\n */\nexport async function handleCacheStrategy_(options: Required<FetchOptions>): Promise<Response> {\n if (options.cacheStrategy === 'network_only') {\n return handleRemoveDuplicate_(options);\n }\n // else handle cache strategies!\n logger_.logMethod?.('_handleCacheStrategy');\n\n if (cacheStorage_ == null && options.cacheStorageName == null) {\n cacheStorage_ = await caches.open('fetch_cache');\n }\n\n const cacheStorage = options.cacheStorageName != null ? await caches.open(options.cacheStorageName) : cacheStorage_;\n\n const request = new Request(options.url, options);\n\n switch (options.cacheStrategy) {\n case 'cache_first': {\n const cachedResponse = await cacheStorage.match(request);\n if (cachedResponse != null) {\n return cachedResponse;\n }\n // else\n const response = await handleRemoveDuplicate_(options);\n if (response.ok) {\n cacheStorage.put(request, response.clone());\n }\n return response;\n }\n\n case 'cache_only': {\n const cachedResponse = await cacheStorage.match(request);\n if (cachedResponse == null) {\n logger_.accident('_handleCacheStrategy', 'fetch_cache_not_found', {url: request.url});\n throw new Error('fetch_cache_not_found');\n }\n // else\n return cachedResponse;\n }\n\n case 'network_first': {\n try {\n const networkResponse = await handleRemoveDuplicate_(options);\n if (networkResponse.ok) {\n cacheStorage.put(request, networkResponse.clone());\n }\n return networkResponse;\n }\n catch (err) {\n const cachedResponse = await cacheStorage.match(request);\n if (cachedResponse != null) {\n return cachedResponse;\n }\n // else\n throw err;\n }\n }\n\n case 'update_cache': {\n const networkResponse = await handleRemoveDuplicate_(options);\n if (networkResponse.ok) {\n cacheStorage.put(request, networkResponse.clone());\n }\n return networkResponse;\n }\n\n case 'stale_while_revalidate': {\n const cachedResponse = await cacheStorage.match(request);\n const fetchedResponsePromise = handleRemoveDuplicate_(options).then((networkResponse) => {\n if (networkResponse.ok) {\n cacheStorage.put(request, networkResponse.clone());\n if (typeof options.revalidateCallback === 'function') {\n setTimeout(options.revalidateCallback, 0, networkResponse.clone());\n }\n }\n return networkResponse;\n });\n\n return cachedResponse ?? fetchedResponsePromise;\n }\n\n default: {\n return handleRemoveDuplicate_(options);\n }\n }\n}\n\n/**\n * Handle Remove Duplicates over `_handleRetryPattern`.\n */\nexport async function handleRemoveDuplicate_(options: Required<FetchOptions>): Promise<Response> {\n if (options.removeDuplicate === 'never') return handleRetryPattern_(options);\n\n logger_.logMethod?.('handleRemoveDuplicate_');\n\n const cacheKey = options.method + ' ' + options.url;\n\n // We must cache fetch promise without await for handle other parallel requests.\n duplicateRequestStorage_[cacheKey] ??= handleRetryPattern_(options);\n\n try {\n // For all requests need to await for clone responses.\n const response = await duplicateRequestStorage_[cacheKey];\n\n if (duplicateRequestStorage_[cacheKey] != null) {\n if (response.ok !== true || options.removeDuplicate === 'until_load') {\n delete duplicateRequestStorage_[cacheKey];\n }\n }\n\n return response.clone();\n }\n catch (err) {\n // clean cache on any error.\n delete duplicateRequestStorage_[cacheKey];\n throw err;\n }\n}\n\n/**\n * Handle retry pattern over `handleTimeout_`.\n */\nexport async function handleRetryPattern_(options: Required<FetchOptions>): Promise<Response> {\n if (!(options.retry > 1)) return handleTimeout_(options);\n\n logger_.logMethod?.('_handleRetryPattern');\n options.retry--;\n\n const externalAbortSignal = options.signal;\n\n try {\n const response = await handleTimeout_(options);\n\n if (response.status < HttpStatusCodes.Error_Server_500_Internal_Server_Error) {\n return response;\n }\n // else\n throw new Error('fetch_server_error');\n }\n catch (err) {\n logger_.accident('fetch', 'fetch_failed_retry', err);\n\n if (globalThis_.navigator?.onLine === false) {\n logger_.accident('handleRetryPattern_', 'offline', 'Skip retry because offline');\n throw err;\n }\n\n await delay.by(options.retryDelay);\n\n options.signal = externalAbortSignal;\n return handleRetryPattern_(options);\n }\n}\n\n/**\n * It's a wrapper around the browser's `fetch` with timeout.\n */\nexport function handleTimeout_(options: FetchOptions): Promise<Response> {\n if (options.timeout === 0) {\n return globalThis_.fetch(options.url, options);\n }\n // else\n logger_.logMethod?.('handleTimeout_');\n return new Promise((resolved, reject) => {\n const abortController = typeof AbortController === 'function' ? new AbortController() : null;\n const externalAbortSignal = options.signal;\n options.signal = abortController?.signal;\n\n if (abortController !== null && externalAbortSignal != null) {\n // Respect external abort signal\n externalAbortSignal.addEventListener('abort', () => abortController.abort(), {once: true});\n }\n\n const timeoutId = setTimeout(() => {\n reject(new Error('fetch_timeout'));\n abortController?.abort('fetch_timeout');\n }, parseDuration(options.timeout!));\n\n // abortController.signal.addEventListener('abort', () => {\n // logger.incident('fetch', 'fetch_abort_signal', {\n // reason: abortController.signal.reason,\n // });\n // });\n\n globalThis_\n .fetch(options.url, options)\n .then((response) => resolved(response))\n .catch((reason) => reject(reason))\n .finally(() => {\n delete options.signal; // try to avoid memory leak in nodejs!\n clearTimeout(timeoutId);\n });\n });\n}\n"],
"mappings": "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",
"names": ["HttpStatusCodes", "HttpStatusCodes"]
}