@naturalcycles/js-lib 14.117.1 → 14.119.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -23,16 +23,16 @@ class AppError extends Error {
23
23
  configurable: true,
24
24
  enumerable: false,
25
25
  });
26
- if (Error.captureStackTrace) {
27
- Error.captureStackTrace(this, this.constructor);
28
- }
29
- else {
30
- Object.defineProperty(this, 'stack', {
31
- value: new Error().stack,
32
- writable: true,
33
- configurable: true,
34
- });
35
- }
26
+ // todo: check if it's needed at all!
27
+ // if (Error.captureStackTrace) {
28
+ // Error.captureStackTrace(this, this.constructor)
29
+ // } else {
30
+ // Object.defineProperty(this, 'stack', {
31
+ // value: new Error().stack, // eslint-disable-line unicorn/error-message
32
+ // writable: true,
33
+ // configurable: true,
34
+ // })
35
+ // }
36
36
  }
37
37
  }
38
38
  exports.AppError = AppError;
@@ -0,0 +1,145 @@
1
+ /// <reference lib="dom" />
2
+ import { CommonLogger } from '../log/commonLogger';
3
+ import type { Promisable } from '../typeFest';
4
+ import type { HttpMethod, HttpStatusFamily } from './http.model';
5
+ export interface FetcherNormalizedCfg extends FetcherCfg, FetcherRequest {
6
+ logger: CommonLogger;
7
+ searchParams: Record<string, any>;
8
+ }
9
+ export interface FetcherCfg {
10
+ baseUrl?: string;
11
+ /**
12
+ * Default rule is that you **are allowed** to mutate req, res, res.retryStatus
13
+ * properties of hook function arguments.
14
+ * If you throw an error from the hook - it will be re-thrown as-is.
15
+ */
16
+ hooks?: {
17
+ /**
18
+ * Allows to mutate req.
19
+ */
20
+ beforeRequest?(req: FetcherRequest): Promisable<void>;
21
+ /**
22
+ * Allows to mutate res.
23
+ * If you set `res.err` - it will be thrown.
24
+ */
25
+ beforeResponse?(res: FetcherResponse): Promisable<void>;
26
+ /**
27
+ * Allows to mutate res.retryStatus to override retry behavior.
28
+ */
29
+ beforeRetry?(res: FetcherResponse): Promisable<void>;
30
+ };
31
+ debug?: boolean;
32
+ logRequest?: boolean;
33
+ logRequestBody?: boolean;
34
+ logResponse?: boolean;
35
+ logResponseBody?: boolean;
36
+ logger?: CommonLogger;
37
+ }
38
+ export interface FetcherRetryStatus {
39
+ retryAttempt: number;
40
+ retryTimeout: number;
41
+ retryStopped: boolean;
42
+ }
43
+ export interface FetcherRetryOptions {
44
+ count: number;
45
+ timeout: number;
46
+ timeoutMax: number;
47
+ timeoutMultiplier: number;
48
+ }
49
+ export interface FetcherRequest extends Omit<FetcherOptions, 'method' | 'headers'> {
50
+ url: string;
51
+ init: RequestInitNormalized;
52
+ throwHttpErrors: boolean;
53
+ timeoutSeconds: number;
54
+ retry: FetcherRetryOptions;
55
+ retryPost: boolean;
56
+ retry4xx: boolean;
57
+ retry5xx: boolean;
58
+ }
59
+ export interface FetcherOptions {
60
+ method?: HttpMethod;
61
+ throwHttpErrors?: boolean;
62
+ /**
63
+ * Default: 30.
64
+ *
65
+ * Timeout applies to both get the response and retrieve the body (e.g `await res.json()`),
66
+ * so both should finish within this single timeout (not each).
67
+ */
68
+ timeoutSeconds?: number;
69
+ json?: any;
70
+ text?: string;
71
+ init?: Partial<RequestInitNormalized>;
72
+ headers?: Record<string, any>;
73
+ mode?: FetcherMode;
74
+ searchParams?: Record<string, any>;
75
+ /**
76
+ * Default is 2 retries (3 tries in total).
77
+ * Pass `retry: { count: 0 }` to disable retries.
78
+ */
79
+ retry?: Partial<FetcherRetryOptions>;
80
+ /**
81
+ * Defaults to false.
82
+ * Set to true to allow retrying `post` requests.
83
+ */
84
+ retryPost?: boolean;
85
+ /**
86
+ * Defaults to false.
87
+ */
88
+ retry4xx?: boolean;
89
+ /**
90
+ * Defaults to true.
91
+ */
92
+ retry5xx?: boolean;
93
+ }
94
+ export type RequestInitNormalized = Omit<RequestInit, 'method' | 'headers'> & {
95
+ method: HttpMethod;
96
+ headers: Record<string, any>;
97
+ };
98
+ export interface FetcherSuccessResponse<BODY = unknown> extends FetcherResponse<BODY> {
99
+ err?: undefined;
100
+ fetchResponse: Response;
101
+ body: BODY;
102
+ }
103
+ export interface FetcherErrorResponse<BODY = unknown> extends FetcherResponse<BODY> {
104
+ err: Error;
105
+ }
106
+ export interface FetcherResponse<BODY = unknown> {
107
+ err?: Error;
108
+ req: FetcherRequest;
109
+ fetchResponse?: Response;
110
+ statusFamily?: HttpStatusFamily;
111
+ body?: BODY;
112
+ retryStatus: FetcherRetryStatus;
113
+ }
114
+ export type FetcherMode = 'json' | 'text';
115
+ /**
116
+ * Experimental wrapper around Fetch.
117
+ * Works in both Browser and Node, using `globalThis.fetch`.
118
+ *
119
+ * @experimental
120
+ */
121
+ export declare class Fetcher {
122
+ private constructor();
123
+ cfg: FetcherNormalizedCfg;
124
+ static create(cfg?: FetcherCfg & FetcherOptions): Fetcher;
125
+ getJson<T = unknown>(url: string, opt?: FetcherOptions): Promise<T>;
126
+ postJson<T = unknown>(url: string, opt?: FetcherOptions): Promise<T>;
127
+ getText(url: string, opt?: FetcherOptions): Promise<string>;
128
+ postText(url: string, opt?: FetcherOptions): Promise<string>;
129
+ fetch<T = unknown>(url: string, opt?: FetcherOptions): Promise<T>;
130
+ rawFetch<T = unknown>(url: string, rawOpt?: FetcherOptions): Promise<FetcherResponse<T>>;
131
+ private processRetry;
132
+ /**
133
+ * Default is yes,
134
+ * unless there's reason not to (e.g method is POST).
135
+ */
136
+ private shouldRetry;
137
+ private getStatusFamily;
138
+ /**
139
+ * Returns url without baseUrl and before ?queryString
140
+ */
141
+ private getShortUrl;
142
+ private normalizeCfg;
143
+ private normalizeOptions;
144
+ }
145
+ export declare function getFetcher(cfg?: FetcherCfg & FetcherOptions): Fetcher;
@@ -0,0 +1,308 @@
1
+ "use strict";
2
+ /// <reference lib="dom"/>
3
+ Object.defineProperty(exports, "__esModule", { value: true });
4
+ exports.getFetcher = exports.Fetcher = void 0;
5
+ const error_util_1 = require("../error/error.util");
6
+ const http_error_1 = require("../error/http.error");
7
+ const number_util_1 = require("../number/number.util");
8
+ const object_util_1 = require("../object/object.util");
9
+ const pDelay_1 = require("../promise/pDelay");
10
+ const json_util_1 = require("../string/json.util");
11
+ const time_util_1 = require("../time/time.util");
12
+ const defRetryOptions = {
13
+ count: 2,
14
+ timeout: 500,
15
+ timeoutMax: 30000,
16
+ timeoutMultiplier: 2,
17
+ };
18
+ /**
19
+ * Experimental wrapper around Fetch.
20
+ * Works in both Browser and Node, using `globalThis.fetch`.
21
+ *
22
+ * @experimental
23
+ */
24
+ class Fetcher {
25
+ constructor(cfg = {}) {
26
+ this.cfg = this.normalizeCfg(cfg);
27
+ }
28
+ static create(cfg = {}) {
29
+ return new Fetcher(cfg);
30
+ }
31
+ async getJson(url, opt = {}) {
32
+ return await this.fetch(url, {
33
+ ...opt,
34
+ mode: 'json',
35
+ });
36
+ }
37
+ async postJson(url, opt = {}) {
38
+ return await this.fetch(url, {
39
+ ...opt,
40
+ method: 'post',
41
+ mode: 'json',
42
+ });
43
+ }
44
+ async getText(url, opt = {}) {
45
+ return await this.fetch(url, {
46
+ ...opt,
47
+ mode: 'text',
48
+ });
49
+ }
50
+ async postText(url, opt = {}) {
51
+ return await this.fetch(url, {
52
+ ...opt,
53
+ method: 'post',
54
+ mode: 'text',
55
+ });
56
+ }
57
+ async fetch(url, opt = {}) {
58
+ const res = await this.rawFetch(url, opt);
59
+ if (res.err) {
60
+ if (res.req.throwHttpErrors)
61
+ throw res.err;
62
+ return res;
63
+ }
64
+ return res.body;
65
+ }
66
+ async rawFetch(url, rawOpt = {}) {
67
+ const { logger } = this.cfg;
68
+ const req = this.normalizeOptions(url, rawOpt);
69
+ const { timeoutSeconds, mode, init: { method }, } = req;
70
+ // setup timeout
71
+ let timeout;
72
+ if (timeoutSeconds) {
73
+ const abortController = new AbortController();
74
+ req.init.signal = abortController.signal;
75
+ timeout = setTimeout(() => {
76
+ abortController.abort(`timeout of ${timeoutSeconds} sec`);
77
+ }, timeoutSeconds * 1000);
78
+ }
79
+ await this.cfg.hooks?.beforeRequest?.(req);
80
+ const res = {
81
+ req,
82
+ retryStatus: {
83
+ retryAttempt: 0,
84
+ retryStopped: false,
85
+ retryTimeout: req.retry.timeout,
86
+ },
87
+ };
88
+ const shortUrl = this.getShortUrl(req.url);
89
+ const signature = [method.toUpperCase(), shortUrl].join(' ');
90
+ /* eslint-disable no-await-in-loop */
91
+ while (!res.retryStatus.retryStopped) {
92
+ const started = Date.now();
93
+ if (this.cfg.logRequest) {
94
+ const { retryAttempt } = res.retryStatus;
95
+ logger.log([' >>', signature, retryAttempt && `try#${retryAttempt + 1}/${req.retry.count}`]
96
+ .filter(Boolean)
97
+ .join(' '));
98
+ if (this.cfg.logRequestBody && req.init.body) {
99
+ logger.log(req.init.body); // todo: check if we can _inspect it
100
+ }
101
+ }
102
+ res.fetchResponse = await globalThis.fetch(req.url, req.init);
103
+ res.statusFamily = this.getStatusFamily(res);
104
+ if (res.fetchResponse.ok) {
105
+ if (mode === 'json') {
106
+ // if no body: set responseBody as {}
107
+ // do not throw a "cannot parse null as Json" error
108
+ res.body = res.fetchResponse.body ? await res.fetchResponse.json() : {};
109
+ }
110
+ else if (mode === 'text') {
111
+ res.body = res.fetchResponse.body ? await res.fetchResponse.text() : '';
112
+ }
113
+ clearTimeout(timeout);
114
+ res.retryStatus.retryStopped = true;
115
+ if (this.cfg.logResponse) {
116
+ const { retryAttempt } = res.retryStatus;
117
+ logger.log([
118
+ ' <<',
119
+ res.fetchResponse.status,
120
+ signature,
121
+ retryAttempt && `try#${retryAttempt + 1}/${req.retry.count}`,
122
+ (0, time_util_1._since)(started),
123
+ ]
124
+ .filter(Boolean)
125
+ .join(' '));
126
+ if (this.cfg.logResponseBody) {
127
+ logger.log(res.body);
128
+ }
129
+ }
130
+ }
131
+ else {
132
+ clearTimeout(timeout);
133
+ const body = (0, json_util_1._jsonParseIfPossible)(await res.fetchResponse.text());
134
+ const errObj = (0, error_util_1._anyToErrorObject)(body);
135
+ const originalMessage = errObj.message;
136
+ errObj.message = [[res.fetchResponse.status, signature].join(' '), originalMessage].join('\n');
137
+ res.err = new http_error_1.HttpError(errObj.message, (0, object_util_1._filterNullishValues)({
138
+ ...errObj.data,
139
+ originalMessage,
140
+ httpStatusCode: res.fetchResponse.status,
141
+ // These properties are provided to be used in e.g custom Sentry error grouping
142
+ // Actually, disabled now, to avoid unnecessary error printing when both msg and data are printed
143
+ // Enabled, cause `data` is not printed by default when error is HttpError
144
+ // method: req.method,
145
+ url: req.url,
146
+ // tryCount: req.tryCount,
147
+ }));
148
+ // We don't log errors when they are also thrown,
149
+ // otherwise it gets logged twice: here, and upstream
150
+ // if (this.cfg.logResponse) {
151
+ // const { retryAttempt } = res.retryStatus
152
+ // logger.error(
153
+ // [
154
+ // [
155
+ // ' <<',
156
+ // res.fetchResponse.status,
157
+ // signature,
158
+ // retryAttempt && `try#${retryAttempt + 1}/${req.retry.count}`,
159
+ // _since(started),
160
+ // ]
161
+ // .filter(Boolean)
162
+ // .join(' '),
163
+ // _stringifyAny(body),
164
+ // ].join('\n'),
165
+ // )
166
+ // }
167
+ await this.processRetry(res);
168
+ }
169
+ }
170
+ await this.cfg.hooks?.beforeResponse?.(res);
171
+ return res;
172
+ }
173
+ async processRetry(res) {
174
+ const { retryStatus } = res;
175
+ if (!this.shouldRetry(res)) {
176
+ retryStatus.retryStopped = true;
177
+ }
178
+ await this.cfg.hooks?.beforeRetry?.(res);
179
+ const { count, timeoutMultiplier, timeoutMax } = res.req.retry;
180
+ if (retryStatus.retryAttempt >= count) {
181
+ retryStatus.retryStopped = true;
182
+ }
183
+ if (retryStatus.retryStopped)
184
+ return;
185
+ retryStatus.retryAttempt++;
186
+ retryStatus.retryTimeout = (0, number_util_1._clamp)(retryStatus.retryTimeout * timeoutMultiplier, 0, timeoutMax);
187
+ await (0, pDelay_1.pDelay)(retryStatus.retryTimeout);
188
+ }
189
+ /**
190
+ * Default is yes,
191
+ * unless there's reason not to (e.g method is POST).
192
+ */
193
+ shouldRetry(res) {
194
+ const { retryPost, retry4xx, retry5xx } = res.req;
195
+ const { method } = res.req.init;
196
+ if (method === 'post' && !retryPost)
197
+ return false;
198
+ const { statusFamily } = res;
199
+ if (statusFamily === '5xx' && !retry5xx)
200
+ return false;
201
+ if (statusFamily === '4xx' && !retry4xx)
202
+ return false;
203
+ return true; // default is true
204
+ }
205
+ getStatusFamily(res) {
206
+ const status = res.fetchResponse?.status;
207
+ if (!status)
208
+ return;
209
+ if (status >= 500)
210
+ return '5xx';
211
+ if (status >= 400)
212
+ return '4xx';
213
+ if (status >= 300)
214
+ return '3xx';
215
+ if (status >= 200)
216
+ return '2xx';
217
+ if (status >= 100)
218
+ return '1xx';
219
+ }
220
+ /**
221
+ * Returns url without baseUrl and before ?queryString
222
+ */
223
+ getShortUrl(url) {
224
+ const { baseUrl } = this.cfg;
225
+ if (!baseUrl)
226
+ return url;
227
+ return url.split('?')[0].slice(baseUrl.length);
228
+ }
229
+ normalizeCfg(cfg) {
230
+ if (cfg.baseUrl?.endsWith('/')) {
231
+ console.warn(`Fetcher: baseUrl should not end with /`);
232
+ cfg.baseUrl = cfg.baseUrl.slice(0, cfg.baseUrl.length - 1);
233
+ }
234
+ const { debug } = cfg;
235
+ const norm = (0, object_util_1._merge)({
236
+ url: '',
237
+ searchParams: {},
238
+ timeoutSeconds: 30,
239
+ throwHttpErrors: true,
240
+ retryPost: false,
241
+ retry4xx: false,
242
+ retry5xx: true,
243
+ logger: console,
244
+ logRequest: debug,
245
+ logRequestBody: debug,
246
+ logResponse: debug,
247
+ logResponseBody: debug,
248
+ retry: { ...defRetryOptions },
249
+ init: {
250
+ method: 'get',
251
+ headers: {},
252
+ },
253
+ }, cfg);
254
+ norm.init.headers = (0, object_util_1._mapKeys)(norm.init.headers, k => k.toLowerCase());
255
+ return norm;
256
+ }
257
+ normalizeOptions(url, opt) {
258
+ const { baseUrl, timeoutSeconds, throwHttpErrors, retryPost, retry4xx, retry5xx, retry } = this.cfg;
259
+ const req = {
260
+ url,
261
+ timeoutSeconds,
262
+ throwHttpErrors,
263
+ retryPost,
264
+ retry4xx,
265
+ retry5xx,
266
+ ...(0, object_util_1._omit)(opt, ['method', 'headers']),
267
+ retry: {
268
+ ...retry,
269
+ ...(0, object_util_1._filterUndefinedValues)(opt.retry || {}),
270
+ },
271
+ init: (0, object_util_1._merge)({ ...this.cfg.init }, opt.init, (0, object_util_1._filterUndefinedValues)({
272
+ method: opt.method,
273
+ headers: (0, object_util_1._mapKeys)(opt.headers || {}, k => k.toLowerCase()),
274
+ })),
275
+ };
276
+ // setup url
277
+ if (baseUrl) {
278
+ if (url.startsWith('/')) {
279
+ console.warn(`Fetcher: url should not start with / when baseUrl is specified`);
280
+ url = url.slice(1);
281
+ }
282
+ req.url = `${baseUrl}/${url}`;
283
+ }
284
+ const searchParams = {
285
+ ...this.cfg.searchParams,
286
+ ...opt.searchParams,
287
+ };
288
+ if (Object.keys(searchParams).length) {
289
+ const qs = new URLSearchParams(searchParams).toString();
290
+ req.url += req.url.includes('?') ? '&' : '?' + qs;
291
+ }
292
+ // setup request body
293
+ if (opt.json !== undefined) {
294
+ req.init.body = JSON.stringify(opt.json);
295
+ req.init.headers['content-type'] = 'application/json';
296
+ }
297
+ else if (opt.text !== undefined) {
298
+ req.init.body = opt.text;
299
+ req.init.headers['content-type'] = 'text/plain';
300
+ }
301
+ return req;
302
+ }
303
+ }
304
+ exports.Fetcher = Fetcher;
305
+ function getFetcher(cfg = {}) {
306
+ return Fetcher.create(cfg);
307
+ }
308
+ exports.getFetcher = getFetcher;
@@ -0,0 +1,2 @@
1
+ export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'head';
2
+ export type HttpStatusFamily = '5xx' | '4xx' | '3xx' | '2xx' | '1xx';
@@ -0,0 +1,2 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
package/dist/index.d.ts CHANGED
@@ -74,4 +74,6 @@ export * from './datetime/localDate';
74
74
  export * from './datetime/localTime';
75
75
  export * from './datetime/dateInterval';
76
76
  export * from './datetime/timeInterval';
77
+ export * from './http/http.model';
78
+ export * from './http/fetcher';
77
79
  export { is };
package/dist/index.js CHANGED
@@ -79,3 +79,5 @@ tslib_1.__exportStar(require("./datetime/localDate"), exports);
79
79
  tslib_1.__exportStar(require("./datetime/localTime"), exports);
80
80
  tslib_1.__exportStar(require("./datetime/dateInterval"), exports);
81
81
  tslib_1.__exportStar(require("./datetime/timeInterval"), exports);
82
+ tslib_1.__exportStar(require("./http/http.model"), exports);
83
+ tslib_1.__exportStar(require("./http/fetcher"), exports);
@@ -101,6 +101,8 @@ export declare function _filterEmptyValues<T extends AnyObject>(obj: T, mutate?:
101
101
  * are applied from left to right. Subsequent sources overwrite property
102
102
  * assignments of previous sources.
103
103
  *
104
+ * Works as "recursive Object.assign".
105
+ *
104
106
  * **Note:** This method mutates `object`.
105
107
  *
106
108
  * @category Object
@@ -186,6 +186,8 @@ exports._filterEmptyValues = _filterEmptyValues;
186
186
  * are applied from left to right. Subsequent sources overwrite property
187
187
  * assignments of previous sources.
188
188
  *
189
+ * Works as "recursive Object.assign".
190
+ *
189
191
  * **Note:** This method mutates `object`.
190
192
  *
191
193
  * @category Object
@@ -209,18 +211,19 @@ exports._filterEmptyValues = _filterEmptyValues;
209
211
  */
210
212
  function _merge(target, ...sources) {
211
213
  sources.forEach(source => {
212
- if ((0, is_util_1._isObject)(source)) {
213
- Object.keys(source).forEach(key => {
214
- if ((0, is_util_1._isObject)(source[key])) {
215
- if (!target[key])
216
- Object.assign(target, { [key]: {} });
217
- _merge(target[key], source[key]);
218
- }
219
- else {
220
- Object.assign(target, { [key]: source[key] });
221
- }
222
- });
223
- }
214
+ if (!(0, is_util_1._isObject)(source))
215
+ return;
216
+ Object.keys(source).forEach(key => {
217
+ if ((0, is_util_1._isObject)(source[key])) {
218
+ ;
219
+ target[key] ||= {};
220
+ _merge(target[key], source[key]);
221
+ }
222
+ else {
223
+ ;
224
+ target[key] = source[key];
225
+ }
226
+ });
224
227
  });
225
228
  return target;
226
229
  }
@@ -56,7 +56,8 @@ function _stringifyAny(obj, opt = {}) {
56
56
  // This is to fix the rare error (happened with Got) where `err.message` was changed,
57
57
  // but err.stack had "old" err.message
58
58
  // This should "fix" that
59
- s = [s, ...obj.stack.split('\n').slice(1)].join('\n');
59
+ const sLines = s.split('\n').length;
60
+ s = [s, ...obj.stack.split('\n').slice(sLines)].join('\n');
60
61
  }
61
62
  if ((0, error_util_1._isErrorObject)(obj)) {
62
63
  if ((0, error_util_1._isHttpErrorObject)(obj)) {
@@ -20,15 +20,15 @@ export class AppError extends Error {
20
20
  configurable: true,
21
21
  enumerable: false,
22
22
  });
23
- if (Error.captureStackTrace) {
24
- Error.captureStackTrace(this, this.constructor);
25
- }
26
- else {
27
- Object.defineProperty(this, 'stack', {
28
- value: new Error().stack,
29
- writable: true,
30
- configurable: true,
31
- });
32
- }
23
+ // todo: check if it's needed at all!
24
+ // if (Error.captureStackTrace) {
25
+ // Error.captureStackTrace(this, this.constructor)
26
+ // } else {
27
+ // Object.defineProperty(this, 'stack', {
28
+ // value: new Error().stack, // eslint-disable-line unicorn/error-message
29
+ // writable: true,
30
+ // configurable: true,
31
+ // })
32
+ // }
33
33
  }
34
34
  }