@naturalcycles/js-lib 14.156.0 → 14.157.1

package/dist/form.util.d.ts

@@ -0,0 +1,9 @@
+import type { AnyObject } from './types';
+/**
+ * Convert any object to FormData.
+ * Please note that every key and value of FormData is `string`.
+ * Even if you pass a number - it'll be converted to string.
+ * Think URLSearchParams.
+ */
+export declare function objectToFormData(obj?: AnyObject): FormData;
+export declare function formDataToObject<T extends AnyObject>(formData: FormData): T;

package/dist/form.util.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formDataToObject = exports.objectToFormData = void 0;
+/**
+ * Convert any object to FormData.
+ * Please note that every key and value of FormData is `string`.
+ * Even if you pass a number - it'll be converted to string.
+ * Think URLSearchParams.
+ */
+function objectToFormData(obj = {}) {
+    const fd = new FormData();
+    Object.entries(obj).forEach(([k, v]) => fd.append(k, v));
+    return fd;
+}
+exports.objectToFormData = objectToFormData;
+function formDataToObject(formData) {
+    return Object.fromEntries(formData);
+}
+exports.formDataToObject = formDataToObject;

package/dist/http/fetcher.d.ts

@@ -1,4 +1,5 @@
 /// <reference lib="dom" />
+/// <reference lib="dom.iterable" />
 import type { FetcherAfterResponseHook, FetcherBeforeRequestHook, FetcherBeforeRetryHook, FetcherCfg, FetcherNormalizedCfg, FetcherOptions, FetcherResponse } from './fetcher.model';
 /**
  * Experimental wrapper around Fetch.

package/dist/http/fetcher.js

@@ -1,5 +1,6 @@
 "use strict";
 /// <reference lib="dom"/>
+/// <reference lib="dom.iterable"/>
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFetcher = exports.Fetcher = void 0;
 const env_1 = require("../env");
@@ -13,6 +14,14 @@ const json_util_1 = require("../string/json.util");
 const stringifyAny_1 = require("../string/stringifyAny");
 const time_util_1 = require("../time/time.util");
 const http_model_1 = require("./http.model");
+const acceptByResponseType = {
+    text: 'text/plain',
+    json: 'application/json',
+    void: '*/*',
+    readableStream: 'application/octet-stream',
+    arrayBuffer: 'application/octet-stream',
+    blob: 'application/octet-stream',
+};
 const defRetryOptions = {
     count: 2,
     timeout: 1000,
@@ -36,18 +45,18 @@ class Fetcher {
                 return await this.fetch({
                     url,
                     method,
-                    mode: 'void',
+                    responseType: 'void',
                     ...opt,
                 });
             };
             if (method === 'HEAD')
-                return // mode=text
+                return // responseType=text
                 ;
             this[`${m}Text`] = async (url, opt) => {
                 return await this.fetch({
                     url,
                     method,
-                    mode: 'text',
+                    responseType: 'text',
                     ...opt,
                 });
             };
@@ -55,7 +64,7 @@ class Fetcher {
                 return await this.fetch({
                     url,
                     method,
-                    mode: 'json',
+                    responseType: 'json',
                     ...opt,
                 });
             };
@@ -82,7 +91,7 @@ class Fetcher {
     static create(cfg = {}) {
         return new Fetcher(cfg);
     }
-    // mode=readableStream
+    // responseType=readableStream
     /**
      * Returns raw fetchResponse.body, which is a ReadableStream<Uint8Array>
      *
@@ -92,7 +101,7 @@ class Fetcher {
     async getReadableStream(url, opt) {
         return await this.fetch({
             url,
-            mode: 'readableStream',
+            responseType: 'readableStream',
             ...opt,
         });
     }
@@ -112,19 +121,6 @@ class Fetcher {
         const req = this.normalizeOptions(opt);
         const { logger } = this.cfg;
         const { timeoutSeconds, init: { method }, } = req;
-        // setup timeout
-        let timeout;
-        if (timeoutSeconds) {
-            const abortController = new AbortController();
-            req.init.signal = abortController.signal;
-            timeout = setTimeout(() => {
-                // Apparently, providing a `string` reason to abort() causes Undici to throw `invalid_argument` error,
-                // so, we're wrapping it in a TimeoutError instance
-                abortController.abort(new pTimeout_1.TimeoutError(`request timed out after ${timeoutSeconds} sec`));
-                // abortController.abort(`timeout of ${timeoutSeconds} sec`)
-                // abortController.abort()
-            }, timeoutSeconds * 1000);
-        }
         for (const hook of this.cfg.hooks.beforeRequest || []) {
             await hook(req);
         }
@@ -143,6 +139,18 @@ class Fetcher {
         };
         while (!res.retryStatus.retryStopped) {
             req.started = Date.now();
+            // setup timeout
+            let timeoutId;
+            if (timeoutSeconds) {
+                const abortController = new AbortController();
+                req.init.signal = abortController.signal;
+                timeoutId = setTimeout(() => {
+                    // console.log(`actual request timed out in ${_since(req.started)}`)
+                    // Apparently, providing a `string` reason to abort() causes Undici to throw `invalid_argument` error,
+                    // so, we're wrapping it in a TimeoutError instance
+                    abortController.abort(new pTimeout_1.TimeoutError(`request timed out after ${timeoutSeconds} sec`));
+                }, timeoutSeconds * 1000);
+            }
             if (this.cfg.logRequest) {
                 const { retryAttempt } = res.retryStatus;
                 logger.log([' >>', signature, retryAttempt && `try#${retryAttempt + 1}/${req.retry.count + 1}`]
@@ -166,14 +174,30 @@ class Fetcher {
                 // important to set it to undefined, otherwise it can keep the previous value (from previous try)
                 res.fetchResponse = undefined;
             }
+            finally {
+                clearTimeout(timeoutId);
+                // Separate Timeout will be introduced to "download and parse the body"
+            }
             res.statusFamily = this.getStatusFamily(res);
             res.statusCode = res.fetchResponse?.status;
             if (res.fetchResponse?.ok) {
-                await this.onOkResponse(res, timeout);
+                try {
+                    // We are applying a separate Timeout (as long as original Timeout for now) to "download and parse the body"
+                    await (0, pTimeout_1.pTimeout)(async () => await this.onOkResponse(res), {
+                        timeout: timeoutSeconds * 1000 || Number.POSITIVE_INFINITY,
+                        name: 'Fetcher.onOkResponse',
+                    });
+                }
+                catch (err) {
+                    // onOkResponse can still fail, e.g when loading/parsing json, text or doing other response manipulation
+                    res.err = (0, error_util_1._anyToError)(err);
+                    res.ok = false;
+                    await this.onNotOkResponse(res);
+                }
             }
             else {
                 // !res.ok
-                await this.onNotOkResponse(res, timeout);
+                await this.onNotOkResponse(res);
             }
         }
         for (const hook of this.cfg.hooks.afterResponse || []) {
@@ -181,31 +205,17 @@ class Fetcher {
         }
         return res;
     }
-    async onOkResponse(res, timeout) {
+    async onOkResponse(res) {
         const { req } = res;
-        const { mode } = res.req;
-        if (mode === 'json') {
+        const { responseType } = res.req;
+        // This function is subject to a separate timeout to "download and parse the data"
+        if (responseType === 'json') {
             if (res.fetchResponse.body) {
                 const text = await res.fetchResponse.text();
                 if (text) {
-                    try {
-                        res.body = text;
-                        res.body = (0, json_util_1._jsonParse)(text, req.jsonReviver);
-                    }
-                    catch (err) {
-                        // Error while parsing json
-                        // res.err = _anyToError(err, HttpRequestError, {
-                        //   requestUrl: res.req.url,
-                        //   requestBaseUrl: this.cfg.baseUrl,
-                        //   requestMethod: res.req.init.method,
-                        //   requestSignature: res.signature,
-                        //   requestDuration: Date.now() - started,
-                        //   responseStatusCode: res.fetchResponse.status,
-                        // } satisfies HttpRequestErrorData)
-                        res.err = (0, error_util_1._anyToError)(err);
-                        res.ok = false;
-                        return await this.onNotOkResponse(res, timeout);
-                    }
+                    res.body = text;
+                    res.body = (0, json_util_1._jsonParse)(text, req.jsonReviver);
+                    // Error while parsing json can happen - it'll be handled upstream
                 }
                 else {
                     // Body had a '' (empty string)
@@ -218,24 +228,22 @@ class Fetcher {
                 res.body = {};
             }
         }
-        else if (mode === 'text') {
+        else if (responseType === 'text') {
             res.body = res.fetchResponse.body ? await res.fetchResponse.text() : '';
         }
-        else if (mode === 'arrayBuffer') {
+        else if (responseType === 'arrayBuffer') {
             res.body = res.fetchResponse.body ? await res.fetchResponse.arrayBuffer() : {};
         }
-        else if (mode === 'blob') {
+        else if (responseType === 'blob') {
             res.body = res.fetchResponse.body ? await res.fetchResponse.blob() : {};
         }
-        else if (mode === 'readableStream') {
+        else if (responseType === 'readableStream') {
             res.body = res.fetchResponse.body;
             if (res.body === null) {
-                res.err = new Error(`fetchResponse.body is null`);
-                res.ok = false;
-                return await this.onNotOkResponse(res, timeout);
+                // Error is to be handled upstream
+                throw new Error(`fetchResponse.body is null`);
             }
         }
-        clearTimeout(timeout);
         res.retryStatus.retryStopped = true;
         // res.err can happen on `failed to fetch` type of error, e.g JSON.parse, CORS, unexpected redirect
         if (!res.err && this.cfg.logResponse) {
@@ -261,8 +269,7 @@ class Fetcher {
     async callNativeFetch(url, init) {
         return await globalThis.fetch(url, init);
     }
-    async onNotOkResponse(res, timeout) {
-        clearTimeout(timeout);
+    async onNotOkResponse(res) {
         let cause;
         if (res.err) {
             // This is only possible on JSON.parse error, or CORS error,
@@ -328,7 +335,11 @@ class Fetcher {
             return;
         retryStatus.retryAttempt++;
         retryStatus.retryTimeout = (0, number_util_1._clamp)(retryStatus.retryTimeout * timeoutMultiplier, 0, timeoutMax);
-        await (0, pDelay_1.pDelay)(this.getRetryTimeout(res));
+        const timeout = this.getRetryTimeout(res);
+        if (res.req.debug) {
+            this.cfg.logger.log(` .. ${res.signature} waiting ${(0, time_util_1._ms)(timeout)}`);
+        }
+        await (0, pDelay_1.pDelay)(timeout);
     }
     getRetryTimeout(res) {
         let timeout = 0;
@@ -383,8 +394,9 @@ class Fetcher {
         if (statusFamily === 3 && !retry3xx)
             return false;
         // should not retry on `unexpected redirect` in error.cause.cause
-        if (res.err?.cause?.cause?.message?.includes('unexpected redirect'))
+        if (res.err?.cause?.cause?.message?.includes('unexpected redirect')) {
             return false;
+        }
         return true; // default is true
     }
     getStatusFamily(res) {
@@ -422,14 +434,14 @@ class Fetcher {
     }
     normalizeCfg(cfg) {
         if (cfg.baseUrl?.endsWith('/')) {
-            console.warn(`Fetcher: baseUrl should not end with /`);
+            console.warn(`Fetcher: baseUrl should not end with slash: ${cfg.baseUrl}`);
             cfg.baseUrl = cfg.baseUrl.slice(0, cfg.baseUrl.length - 1);
         }
         const { debug = false } = cfg;
         const norm = (0, object_util_1._merge)({
             baseUrl: '',
             inputUrl: '',
-            mode: 'void',
+            responseType: 'void',
             searchParams: {},
             timeoutSeconds: 30,
             retryPost: false,
@@ -448,7 +460,10 @@ class Fetcher {
             retry: { ...defRetryOptions },
             init: {
                 method: cfg.method || 'GET',
-                headers: cfg.headers || {},
+                headers: {
+                    'user-agent': 'fetcher',
+                    ...cfg.headers,
+                },
                 credentials: cfg.credentials,
                 redirect: cfg.redirect,
             },
@@ -464,12 +479,13 @@ class Fetcher {
                 'retryPost',
                 'retry4xx',
                 'retry5xx',
-                'mode',
+                'responseType',
                 'jsonReviver',
                 'logRequest',
                 'logRequestBody',
                 'logResponse',
                 'logResponseBody',
+                'debug',
             ]),
             started: Date.now(),
             ...(0, object_util_1._omit)(opt, ['method', 'headers', 'credentials']),
@@ -514,9 +530,20 @@ class Fetcher {
             req.init.body = opt.text;
             req.init.headers['content-type'] = 'text/plain';
         }
+        else if (opt.form) {
+            if (opt.form instanceof URLSearchParams || opt.form instanceof FormData) {
+                req.init.body = opt.form;
+            }
+            else {
+                req.init.body = new URLSearchParams(opt.form);
+            }
+            req.init.headers['content-type'] = 'application/x-www-form-urlencoded';
+        }
         else if (opt.body !== undefined) {
             req.init.body = opt.body;
         }
+        // Unless `accept` header was already set - set it based on responseType
+        req.init.headers['accept'] ||= acceptByResponseType[req.responseType];
         return req;
     }
 }

package/dist/http/fetcher.model.d.ts

@@ -1,8 +1,8 @@
 import type { CommonLogger } from '../log/commonLogger';
 import type { Promisable } from '../typeFest';
-import type { Reviver, UnixTimestampMillisNumber } from '../types';
+import type { AnyObject, NumberOfMilliseconds, Reviver, UnixTimestampMillisNumber } from '../types';
 import type { HttpMethod, HttpStatusFamily } from './http.model';
-export interface FetcherNormalizedCfg extends Required<FetcherCfg>, Omit<FetcherRequest, 'started' | 'fullUrl' | 'logRequest' | 'logRequestBody' | 'logResponse' | 'logResponseBody' | 'redirect' | 'credentials'> {
+export interface FetcherNormalizedCfg extends Required<FetcherCfg>, Omit<FetcherRequest, 'started' | 'fullUrl' | 'logRequest' | 'logRequestBody' | 'logResponse' | 'logResponseBody' | 'debug' | 'redirect' | 'credentials'> {
     logger: CommonLogger;
     searchParams: Record<string, any>;
 }
@@ -68,13 +68,13 @@ export interface FetcherCfg {
 }
 export interface FetcherRetryStatus {
     retryAttempt: number;
-    retryTimeout: number;
+    retryTimeout: NumberOfMilliseconds;
     retryStopped: boolean;
 }
 export interface FetcherRetryOptions {
     count: number;
-    timeout: number;
-    timeoutMax: number;
+    timeout: NumberOfMilliseconds;
+    timeoutMax: NumberOfMilliseconds;
     timeoutMultiplier: number;
 }
 export interface FetcherRequest extends Omit<FetcherOptions, 'method' | 'headers' | 'baseUrl' | 'url'> {
@@ -88,7 +88,7 @@ export interface FetcherRequest extends Omit<FetcherOptions, 'method' | 'headers
      */
     fullUrl: string;
     init: RequestInitNormalized;
-    mode: FetcherMode;
+    responseType: FetcherResponseType;
     timeoutSeconds: number;
     retry: FetcherRetryOptions;
     retryPost: boolean;
@@ -112,14 +112,29 @@ export interface FetcherOptions {
      * so both should finish within this single timeout (not each).
      */
     timeoutSeconds?: number;
-    json?: any;
-    text?: string;
     /**
      * Supports all the types that RequestInit.body supports.
      *
      * Useful when you want to e.g pass FormData.
      */
     body?: Blob | BufferSource | FormData | URLSearchParams | string;
+    /**
+     * Same as `body`, but also conveniently sets the
+     * Content-Type header to `text/plain`
+     */
+    text?: string;
+    /**
+     * Same as `body`, but:
+     * 1. JSON.stringifies the passed variable
+     * 2. Conveniently sets the Content-Type header to `application/json`
+     */
+    json?: any;
+    /**
+     * Same as `body`, but:
+     * 1. Transforms the passed plain js object into URLSearchParams and passes it to `body`
+     * 2. Conveniently sets the Content-Type header to `application/x-www-form-urlencoded`
+     */
+    form?: FormData | URLSearchParams | AnyObject;
     credentials?: RequestCredentials;
     /**
      * Default to 'follow'.
@@ -128,7 +143,7 @@ export interface FetcherOptions {
      */
     redirect?: RequestRedirect;
     headers?: Record<string, any>;
-    mode?: FetcherMode;
+    responseType?: FetcherResponseType;
     searchParams?: Record<string, any>;
     /**
      * Default is 2 retries (3 tries in total).
@@ -157,6 +172,10 @@ export interface FetcherOptions {
     logRequestBody?: boolean;
     logResponse?: boolean;
     logResponseBody?: boolean;
+    /**
+     * If true - enables all possible logging.
+     */
+    debug?: boolean;
 }
 export type RequestInitNormalized = Omit<RequestInit, 'method' | 'headers'> & {
     method: HttpMethod;
@@ -185,4 +204,4 @@ export interface FetcherErrorResponse<BODY = unknown> {
     signature: string;
 }
 export type FetcherResponse<BODY = unknown> = FetcherSuccessResponse<BODY> | FetcherErrorResponse<BODY>;
-export type FetcherMode = 'json' | 'text' | 'void' | 'arrayBuffer' | 'blob' | 'readableStream';
+export type FetcherResponseType = 'json' | 'text' | 'void' | 'arrayBuffer' | 'blob' | 'readableStream';

package/dist/index.d.ts

@@ -80,6 +80,7 @@ export * from './http/fetcher';
 export * from './http/fetcher.model';
 export * from './string/hash.util';
 export * from './env/buildInfo';
+export * from './form.util';
 export * from './zod/zod.util';
 export * from './zod/zod.shared.schemas';
 import { z, ZodSchema, ZodError, ZodIssue } from 'zod';

package/dist/index.js

@@ -84,6 +84,7 @@ tslib_1.__exportStar(require("./http/fetcher"), exports);
 tslib_1.__exportStar(require("./http/fetcher.model"), exports);
 tslib_1.__exportStar(require("./string/hash.util"), exports);
 tslib_1.__exportStar(require("./env/buildInfo"), exports);
+tslib_1.__exportStar(require("./form.util"), exports);
 tslib_1.__exportStar(require("./zod/zod.util"), exports);
 tslib_1.__exportStar(require("./zod/zod.shared.schemas"), exports);
 const zod_1 = require("zod");

package/dist/promise/pTimeout.d.ts

@@ -1,6 +1,6 @@
 import { AppError } from '../error/app.error';
 import type { ErrorData, ErrorObject } from '../error/error.model';
-import type { AnyAsyncFunction } from '../types';
+import type { AnyAsyncFunction, NumberOfMilliseconds } from '../types';
 export declare class TimeoutError extends AppError {
     constructor(message: string, data?: {}, cause?: ErrorObject);
 }
@@ -8,7 +8,7 @@ export interface PTimeoutOptions {
     /**
      * Timeout in milliseconds.
      */
-    timeout: number;
+    timeout: NumberOfMilliseconds;
     /**
      * If set - will be included in the error message.
      * Can be used to identify the place in the code that failed.

package/dist-esm/form.util.js

@@ -0,0 +1,14 @@
+/**
+ * Convert any object to FormData.
+ * Please note that every key and value of FormData is `string`.
+ * Even if you pass a number - it'll be converted to string.
+ * Think URLSearchParams.
+ */
+export function objectToFormData(obj = {}) {
+    const fd = new FormData();
+    Object.entries(obj).forEach(([k, v]) => fd.append(k, v));
+    return fd;
+}
+export function formDataToObject(formData) {
+    return Object.fromEntries(formData);
+}