@naturalcycles/js-lib 14.170.0 → 14.172.0

package/dist/error/error.model.d.ts

@@ -17,6 +17,14 @@ export interface ErrorData {
      * Error id in some error tracking system (e.g Sentry).
      */
     errorId?: string;
+    /**
+     * If set - provides a short semi-user-friendly error message snippet,
+     * that would allow to give a hint to the user what went wrong,
+     * also to developers and CS to distinguish between different errors.
+     *
+     * It's not supposed to have full information about the error, just a small extract from it.
+     */
+    snippet?: string;
     /**
      * Set to true to force reporting this error (e.g to Sentry).
      * Useful to be able to force-report e.g a 4xx error, which by default wouldn't be reported.
@@ -35,11 +43,6 @@ export interface ErrorData {
      * E.g 0.1 will report 10% of errors (and ignore the 90%)
      */
     reportRate?: number;
-    /**
-     * Sometimes error.message gets "decorated" with extra information
-     * (e.g frontend-lib adds a method, url, etc for all the errors)
-     * `originalMessage` is used to preserve the original `error.message` as it came from the backend.
-     */
     /**
      * Can be used by error-reporting tools (e.g Sentry).
      * If fingerprint is defined - it'll be used INSTEAD of default fingerprint of a tool.

package/dist/error/error.util.d.ts

@@ -18,6 +18,22 @@ export declare function _anyToError<ERROR_TYPE extends Error = Error>(o: any, er
 export declare function _anyToErrorObject<DATA_TYPE extends ErrorData = ErrorData>(o: any, errorData?: Partial<DATA_TYPE>): ErrorObject<DATA_TYPE>;
 export declare function _errorLikeToErrorObject<DATA_TYPE extends ErrorData = ErrorData>(e: AppError<DATA_TYPE> | Error | ErrorLike): ErrorObject<DATA_TYPE>;
 export declare function _errorObjectToError<DATA_TYPE extends ErrorData, ERROR_TYPE extends Error>(o: ErrorObject<DATA_TYPE>, errorClass?: Class<ERROR_TYPE>): ERROR_TYPE;
+export interface ErrorSnippetOptions {
+    /**
+     * Max length of the error line.
+     * Snippet may have multiple lines, one original and one per `cause`.
+     */
+    maxLineLength?: number;
+    maxLines?: number;
+}
+/**
+ * Provides a short semi-user-friendly error message snippet,
+ * that would allow to give a hint to the user what went wrong,
+ * also to developers and CS to distinguish between different errors.
+ *
+ * It's not supposed to have full information about the error, just a small extract from it.
+ */
+export declare function _errorSnippet(err: any, opt?: ErrorSnippetOptions): string;
 export declare function _isBackendErrorResponseObject(o: any): o is BackendErrorResponseObject;
 export declare function _isHttpRequestErrorObject(o: any): o is ErrorObject<HttpRequestErrorData>;
 /**

package/dist/error/error.util.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._errorDataAppend = exports._isErrorLike = exports._isErrorObject = exports._isHttpRequestErrorObject = exports._isBackendErrorResponseObject = exports._errorObjectToError = exports._errorLikeToErrorObject = exports._anyToErrorObject = exports._anyToError = void 0;
+exports._errorDataAppend = exports._isErrorLike = exports._isErrorObject = exports._isHttpRequestErrorObject = exports._isBackendErrorResponseObject = exports._errorSnippet = exports._errorObjectToError = exports._errorLikeToErrorObject = exports._anyToErrorObject = exports._anyToError = void 0;
 const __1 = require("..");
 /**
  * Useful to ensure that error in `catch (err) { ... }`
@@ -38,7 +38,6 @@ exports._anyToError = _anyToError;
  */
 function _anyToErrorObject(o, errorData) {
     let eo;
-    // if (o instanceof Error) {
     if (_isErrorLike(o)) {
         eo = _errorLikeToErrorObject(o);
     }
@@ -71,6 +70,14 @@ function _anyToErrorObject(o, errorData) {
 }
 exports._anyToErrorObject = _anyToErrorObject;
 function _errorLikeToErrorObject(e) {
+    // If it's already an ErrorObject - just return it
+    // AppError satisfies ErrorObject interface
+    // Error does not satisfy (lacks `data`)
+    // UPD: no, we expect a "plain object" here as an output,
+    // because Error classes sometimes have non-enumerable properties (e.g data)
+    if (!(e instanceof Error) && _isErrorObject(e)) {
+        return e;
+    }
     const obj = {
         name: e.name,
         message: e.message,
@@ -129,6 +136,48 @@ function _errorObjectToError(o, errorClass = Error) {
     return err;
 }
 exports._errorObjectToError = _errorObjectToError;
+// These "common" error classes will not be printed as part of the Error snippet
+const commonErrorClasses = new Set([
+    'Error',
+    'AppError',
+    'AssertionError',
+    'HttpRequestError',
+    'JoiValidationError',
+]);
+/**
+ * Provides a short semi-user-friendly error message snippet,
+ * that would allow to give a hint to the user what went wrong,
+ * also to developers and CS to distinguish between different errors.
+ *
+ * It's not supposed to have full information about the error, just a small extract from it.
+ */
+function _errorSnippet(err, opt = {}) {
+    const { maxLineLength = 60, maxLines = 3 } = opt;
+    const e = _anyToErrorObject(err);
+    const lines = [errorObjectToSnippet(e)];
+    let { cause } = e;
+    while (cause && lines.length < maxLines) {
+        lines.push('Caused by ' + errorObjectToSnippet(cause));
+        cause = cause.cause; // insert DiCaprio Inception meme
+    }
+    return lines.map(line => (0, __1._truncate)(line, maxLineLength)).join('\n');
+    function errorObjectToSnippet(e) {
+        // Return snippet if it was already prepared
+        if (e.data.snippet)
+            return e.data.snippet;
+        // Code already serves the purpose of the snippet, so we can just return it
+        if (e.data.code)
+            return e.data.code;
+        return [
+            !commonErrorClasses.has(e.name) && e.name,
+            // replace "1+ white space characters" with a single space
+            e.message.replaceAll(/\s+/gm, ' ').trim(),
+        ]
+            .filter(Boolean)
+            .join(': ');
+    }
+}
+exports._errorSnippet = _errorSnippet;
 function _isBackendErrorResponseObject(o) {
     return _isErrorObject(o?.error);
 }

package/dist/http/fetcher.d.ts

@@ -8,6 +8,14 @@ import type { FetcherAfterResponseHook, FetcherBeforeRequestHook, FetcherBeforeR
  * Works in both Browser and Node, using `globalThis.fetch`.
  */
 export declare class Fetcher {
+    /**
+     * Included in UserAgent when run in Node.
+     * In the browser it's not included, as we want "browser own" UserAgent to be included instead.
+     *
+     * Version is to be incremented every time a difference in behaviour (or a bugfix) is done.
+     */
+    static readonly VERSION = 1;
+    static readonly userAgent: string | undefined;
     private constructor();
     /**
      * Add BeforeRequest hook at the end of the hooks list.

package/dist/http/fetcher.js

@@ -34,6 +34,14 @@ const defRetryOptions = {
  * Works in both Browser and Node, using `globalThis.fetch`.
  */
 class Fetcher {
+    /**
+     * Included in UserAgent when run in Node.
+     * In the browser it's not included, as we want "browser own" UserAgent to be included instead.
+     *
+     * Version is to be incremented every time a difference in behaviour (or a bugfix) is done.
+     */
+    static { this.VERSION = 1; }
+    static { this.userAgent = (0, env_1.isServerSide)() ? `fetcher${this.VERSION}` : undefined; }
     constructor(cfg = {}) {
         if (typeof globalThis.fetch !== 'function') {
             throw new TypeError(`globalThis.fetch is not available`);
@@ -487,10 +495,10 @@ class Fetcher {
             retry: { ...defRetryOptions },
             init: {
                 method: cfg.method || 'GET',
-                headers: {
-                    'user-agent': 'fetcher',
+                headers: (0, object_util_1._filterNullishValues)({
+                    'user-agent': Fetcher.userAgent,
                     ...cfg.headers,
-                },
+                }),
                 credentials: cfg.credentials,
                 redirect: cfg.redirect,
             },
@@ -532,6 +540,8 @@ class Fetcher {
                 headers: (0, object_util_1._mapKeys)(opt.headers || {}, k => k.toLowerCase()),
             }),
         };
+        // Because all header values are stringified, so `a: undefined` becomes `undefined` as a string
+        (0, object_util_1._filterNullishValues)(req.init.headers, true);
         // setup url
         const baseUrl = opt.baseUrl || this.cfg.baseUrl;
         if (baseUrl) {

package/dist/index.d.ts

@@ -86,6 +86,5 @@ export * from './web';
 export * from './zod/zod.util';
 export * from './zod/zod.shared.schemas';
 import { z, ZodSchema, ZodError, ZodIssue } from 'zod';
-import { is } from './vendor/is';
-export { is, z, ZodSchema, ZodError };
+export { z, ZodSchema, ZodError };
 export type { ZodIssue };

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZodError = exports.ZodSchema = exports.z = exports.is = void 0;
+exports.ZodError = exports.ZodSchema = exports.z = void 0;
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./array/array.util"), exports);
 tslib_1.__exportStar(require("./define"), exports);
@@ -93,5 +93,3 @@ const zod_1 = require("zod");
 Object.defineProperty(exports, "z", { enumerable: true, get: function () { return zod_1.z; } });
 Object.defineProperty(exports, "ZodSchema", { enumerable: true, get: function () { return zod_1.ZodSchema; } });
 Object.defineProperty(exports, "ZodError", { enumerable: true, get: function () { return zod_1.ZodError; } });
-const is_1 = require("./vendor/is");
-Object.defineProperty(exports, "is", { enumerable: true, get: function () { return is_1.is; } });

package/dist-esm/error/error.util.js

@@ -1,4 +1,4 @@
-import { AppError, _jsonParseIfPossible, _stringifyAny } from '..';
+import { AppError, _jsonParseIfPossible, _stringifyAny, _truncate } from '..';
 /**
  * Useful to ensure that error in `catch (err) { ... }`
  * is indeed an Error (and not e.g `string` or `undefined`).
@@ -31,7 +31,6 @@ export function _anyToError(o, errorClass = Error, errorData) {
  */
 export function _anyToErrorObject(o, errorData) {
     let eo;
-    // if (o instanceof Error) {
     if (_isErrorLike(o)) {
         eo = _errorLikeToErrorObject(o);
     }
@@ -63,6 +62,14 @@ export function _anyToErrorObject(o, errorData) {
     return eo;
 }
 export function _errorLikeToErrorObject(e) {
+    // If it's already an ErrorObject - just return it
+    // AppError satisfies ErrorObject interface
+    // Error does not satisfy (lacks `data`)
+    // UPD: no, we expect a "plain object" here as an output,
+    // because Error classes sometimes have non-enumerable properties (e.g data)
+    if (!(e instanceof Error) && _isErrorObject(e)) {
+        return e;
+    }
     const obj = {
         name: e.name,
         message: e.message,
@@ -119,6 +126,47 @@ export function _errorObjectToError(o, errorClass = Error) {
     }
     return err;
 }
+// These "common" error classes will not be printed as part of the Error snippet
+const commonErrorClasses = new Set([
+    'Error',
+    'AppError',
+    'AssertionError',
+    'HttpRequestError',
+    'JoiValidationError',
+]);
+/**
+ * Provides a short semi-user-friendly error message snippet,
+ * that would allow to give a hint to the user what went wrong,
+ * also to developers and CS to distinguish between different errors.
+ *
+ * It's not supposed to have full information about the error, just a small extract from it.
+ */
+export function _errorSnippet(err, opt = {}) {
+    const { maxLineLength = 60, maxLines = 3 } = opt;
+    const e = _anyToErrorObject(err);
+    const lines = [errorObjectToSnippet(e)];
+    let { cause } = e;
+    while (cause && lines.length < maxLines) {
+        lines.push('Caused by ' + errorObjectToSnippet(cause));
+        cause = cause.cause; // insert DiCaprio Inception meme
+    }
+    return lines.map(line => _truncate(line, maxLineLength)).join('\n');
+    function errorObjectToSnippet(e) {
+        // Return snippet if it was already prepared
+        if (e.data.snippet)
+            return e.data.snippet;
+        // Code already serves the purpose of the snippet, so we can just return it
+        if (e.data.code)
+            return e.data.code;
+        return [
+            !commonErrorClasses.has(e.name) && e.name,
+            // replace "1+ white space characters" with a single space
+            e.message.replaceAll(/\s+/gm, ' ').trim(),
+        ]
+            .filter(Boolean)
+            .join(': ');
+    }
+}
 export function _isBackendErrorResponseObject(o) {
     return _isErrorObject(o === null || o === void 0 ? void 0 : o.error);
 }

package/dist-esm/http/fetcher.js

@@ -1,5 +1,6 @@
 /// <reference lib="dom"/>
 /// <reference lib="dom.iterable"/>
+var _a;
 import { isServerSide } from '../env';
 import { _assertErrorClassOrRethrow } from '../error/assert';
 import { _anyToError, _anyToErrorObject, _errorLikeToErrorObject } from '../error/error.util';
@@ -60,21 +61,21 @@ export class Fetcher {
      * Add BeforeRequest hook at the end of the hooks list.
      */
     onBeforeRequest(hook) {
-        var _a;
+        var _b;
         ;
-        ((_a = this.cfg.hooks).beforeRequest || (_a.beforeRequest = [])).push(hook);
+        ((_b = this.cfg.hooks).beforeRequest || (_b.beforeRequest = [])).push(hook);
         return this;
     }
     onAfterResponse(hook) {
-        var _a;
+        var _b;
         ;
-        ((_a = this.cfg.hooks).afterResponse || (_a.afterResponse = [])).push(hook);
+        ((_b = this.cfg.hooks).afterResponse || (_b.afterResponse = [])).push(hook);
         return this;
     }
     onBeforeRetry(hook) {
-        var _a;
+        var _b;
         ;
-        ((_a = this.cfg.hooks).beforeRetry || (_a.beforeRetry = [])).push(hook);
+        ((_b = this.cfg.hooks).beforeRetry || (_b.beforeRetry = [])).push(hook);
         return this;
     }
     static create(cfg = {}) {
@@ -120,7 +121,7 @@ export class Fetcher {
      * Note: responseType defaults to `void`, so, override it if you expect different.
      */
     async doFetch(opt) {
-        var _a, _b;
+        var _b, _c;
         const req = this.normalizeOptions(opt);
         const { logger } = this.cfg;
         const { timeoutSeconds, init: { method }, } = req;
@@ -182,8 +183,8 @@ export class Fetcher {
                 // Separate Timeout will be introduced to "download and parse the body"
             }
             res.statusFamily = this.getStatusFamily(res);
-            res.statusCode = (_a = res.fetchResponse) === null || _a === void 0 ? void 0 : _a.status;
-            if ((_b = res.fetchResponse) === null || _b === void 0 ? void 0 : _b.ok) {
+            res.statusCode = (_b = res.fetchResponse) === null || _b === void 0 ? void 0 : _b.status;
+            if ((_c = res.fetchResponse) === null || _c === void 0 ? void 0 : _c.ok) {
                 try {
                     // We are applying a separate Timeout (as long as original Timeout for now) to "download and parse the body"
                     await pTimeout(async () => await this.onOkResponse(res), {
@@ -274,7 +275,7 @@ export class Fetcher {
         return await globalThis.fetch(url, init);
     }
     async onNotOkResponse(res) {
-        var _a, _b;
+        var _b, _c;
         let cause;
         if (res.err) {
             // This is only possible on JSON.parse error, or CORS error,
@@ -293,10 +294,10 @@ export class Fetcher {
             message: 'Fetch failed',
             data: {},
         });
-        const message = [(_a = res.fetchResponse) === null || _a === void 0 ? void 0 : _a.status, res.signature].filter(Boolean).join(' ');
+        const message = [(_b = res.fetchResponse) === null || _b === void 0 ? void 0 : _b.status, res.signature].filter(Boolean).join(' ');
         res.err = new HttpRequestError(message, _filterNullishValues({
             response: res.fetchResponse,
-            responseStatusCode: ((_b = res.fetchResponse) === null || _b === void 0 ? void 0 : _b.status) || 0,
+            responseStatusCode: ((_c = res.fetchResponse) === null || _c === void 0 ? void 0 : _c.status) || 0,
             // These properties are provided to be used in e.g custom Sentry error grouping
             // Actually, disabled now, to avoid unnecessary error printing when both msg and data are printed
             // Enabled, cause `data` is not printed by default when error is HttpError
@@ -313,7 +314,7 @@ export class Fetcher {
         await this.processRetry(res);
     }
     async processRetry(res) {
-        var _a;
+        var _b;
         const { retryStatus } = res;
         if (!this.shouldRetry(res)) {
             retryStatus.retryStopped = true;
@@ -333,7 +334,7 @@ export class Fetcher {
         if (res.err && (!retryStatus.retryStopped || res.req.logResponse)) {
             this.cfg.logger.error([
                 ' <<',
-                ((_a = res.fetchResponse) === null || _a === void 0 ? void 0 : _a.status) || 0,
+                ((_b = res.fetchResponse) === null || _b === void 0 ? void 0 : _b.status) || 0,
                 res.signature,
                 count &&
                     (retryStatus.retryAttempt || !retryStatus.retryStopped) &&
@@ -356,12 +357,12 @@ export class Fetcher {
         await pDelay(timeout);
     }
     getRetryTimeout(res) {
-        var _a;
+        var _b;
         let timeout = 0;
         // Handling http 429 with specific retry headers
         // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
         if (res.fetchResponse && [429, 503].includes(res.fetchResponse.status)) {
-            const retryAfterStr = (_a = res.fetchResponse.headers.get('retry-after')) !== null && _a !== void 0 ? _a : res.fetchResponse.headers.get('x-ratelimit-reset');
+            const retryAfterStr = (_b = res.fetchResponse.headers.get('retry-after')) !== null && _b !== void 0 ? _b : res.fetchResponse.headers.get('x-ratelimit-reset');
             if (retryAfterStr) {
                 if (Number(retryAfterStr)) {
                     timeout = Number(retryAfterStr) * 1000;
@@ -391,13 +392,13 @@ export class Fetcher {
      * statusCode of 0 (or absense of it) will BE retried.
      */
     shouldRetry(res) {
-        var _a, _b, _c, _d, _e;
+        var _b, _c, _d, _e, _f;
         const { retryPost, retry3xx, retry4xx, retry5xx } = res.req;
         const { method } = res.req.init;
         if (method === 'POST' && !retryPost)
             return false;
         const { statusFamily } = res;
-        const statusCode = ((_a = res.fetchResponse) === null || _a === void 0 ? void 0 : _a.status) || 0;
+        const statusCode = ((_b = res.fetchResponse) === null || _b === void 0 ? void 0 : _b.status) || 0;
         if (statusFamily === 5 && !retry5xx)
             return false;
         if ([408, 429].includes(statusCode)) {
@@ -409,14 +410,14 @@ export class Fetcher {
         if (statusFamily === 3 && !retry3xx)
             return false;
         // should not retry on `unexpected redirect` in error.cause.cause
-        if ((_e = (_d = (_c = (_b = res.err) === null || _b === void 0 ? void 0 : _b.cause) === null || _c === void 0 ? void 0 : _c.cause) === null || _d === void 0 ? void 0 : _d.message) === null || _e === void 0 ? void 0 : _e.includes('unexpected redirect')) {
+        if ((_f = (_e = (_d = (_c = res.err) === null || _c === void 0 ? void 0 : _c.cause) === null || _d === void 0 ? void 0 : _d.cause) === null || _e === void 0 ? void 0 : _e.message) === null || _f === void 0 ? void 0 : _f.includes('unexpected redirect')) {
             return false;
         }
         return true; // default is true
     }
     getStatusFamily(res) {
-        var _a;
-        const status = (_a = res.fetchResponse) === null || _a === void 0 ? void 0 : _a.status;
+        var _b;
+        const status = (_b = res.fetchResponse) === null || _b === void 0 ? void 0 : _b.status;
         if (!status)
             return;
         if (status >= 500)
@@ -449,8 +450,8 @@ export class Fetcher {
         return shortUrl;
     }
     normalizeCfg(cfg) {
-        var _a;
-        if ((_a = cfg.baseUrl) === null || _a === void 0 ? void 0 : _a.endsWith('/')) {
+        var _b;
+        if ((_b = cfg.baseUrl) === null || _b === void 0 ? void 0 : _b.endsWith('/')) {
             console.warn(`Fetcher: baseUrl should not end with slash: ${cfg.baseUrl}`);
             cfg.baseUrl = cfg.baseUrl.slice(0, cfg.baseUrl.length - 1);
         }
@@ -477,7 +478,7 @@ export class Fetcher {
             retry: Object.assign({}, defRetryOptions),
             init: {
                 method: cfg.method || 'GET',
-                headers: Object.assign({ 'user-agent': 'fetcher' }, cfg.headers),
+                headers: _filterNullishValues(Object.assign({ 'user-agent': Fetcher.userAgent }, cfg.headers)),
                 credentials: cfg.credentials,
                 redirect: cfg.redirect,
             },
@@ -487,7 +488,7 @@ export class Fetcher {
         return norm;
     }
     normalizeOptions(opt) {
-        var _a;
+        var _b;
         const req = Object.assign(Object.assign(Object.assign(Object.assign({}, _pick(this.cfg, [
             'timeoutSeconds',
             'retryPost',
@@ -503,6 +504,8 @@ export class Fetcher {
         ])), { started: Date.now() }), _omit(opt, ['method', 'headers', 'credentials'])), { inputUrl: opt.url || '', fullUrl: opt.url || '', retry: Object.assign(Object.assign({}, this.cfg.retry), _filterUndefinedValues(opt.retry || {})), init: _merge(Object.assign(Object.assign({}, this.cfg.init), { headers: Object.assign({}, this.cfg.init.headers), method: opt.method || this.cfg.init.method, credentials: opt.credentials || this.cfg.init.credentials, redirect: opt.redirect || this.cfg.init.redirect || 'follow' }), {
                 headers: _mapKeys(opt.headers || {}, k => k.toLowerCase()),
             }) });
+        // Because all header values are stringified, so `a: undefined` becomes `undefined` as a string
+        _filterNullishValues(req.init.headers, true);
         // setup url
         const baseUrl = opt.baseUrl || this.cfg.baseUrl;
         if (baseUrl) {
@@ -540,10 +543,19 @@ export class Fetcher {
             req.init.body = opt.body;
         }
         // Unless `accept` header was already set - set it based on responseType
-        (_a = req.init.headers)['accept'] || (_a['accept'] = acceptByResponseType[req.responseType]);
+        (_b = req.init.headers)['accept'] || (_b['accept'] = acceptByResponseType[req.responseType]);
         return req;
     }
 }
+_a = Fetcher;
+/**
+ * Included in UserAgent when run in Node.
+ * In the browser it's not included, as we want "browser own" UserAgent to be included instead.
+ *
+ * Version is to be incremented every time a difference in behaviour (or a bugfix) is done.
+ */
+Fetcher.VERSION = 1;
+Fetcher.userAgent = isServerSide() ? `fetcher${_a.VERSION}` : undefined;
 export function getFetcher(cfg = {}) {
     return Fetcher.create(cfg);
 }

package/dist-esm/index.js

@@ -86,5 +86,4 @@ export * from './web';
 export * from './zod/zod.util';
 export * from './zod/zod.shared.schemas';
 import { z, ZodSchema, ZodError } from 'zod';
-import { is } from './vendor/is';
-export { is, z, ZodSchema, ZodError };
+export { z, ZodSchema, ZodError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.170.0",
+  "version": "14.172.0",
   "scripts": {
     "prepare": "husky install",
     "build-prod": "build-prod-esm-cjs",
@@ -14,7 +14,7 @@
   "devDependencies": {
     "@naturalcycles/bench-lib": "^1.5.0",
     "@naturalcycles/dev-lib": "^13.0.1",
-    "@naturalcycles/nodejs-lib": "^12.33.4",
+    "@naturalcycles/nodejs-lib": "^13.0.1",
     "@naturalcycles/time-lib": "^3.5.1",
     "@types/crypto-js": "^4.1.1",
     "@types/node": "^20.1.0",

package/src/error/error.model.ts

@@ -21,6 +21,15 @@ export interface ErrorData {
    */
   errorId?: string
 
+  /**
+   * If set - provides a short semi-user-friendly error message snippet,
+   * that would allow to give a hint to the user what went wrong,
+   * also to developers and CS to distinguish between different errors.
+   *
+   * It's not supposed to have full information about the error, just a small extract from it.
+   */
+  snippet?: string
+
   /**
    * Set to true to force reporting this error (e.g to Sentry).
    * Useful to be able to force-report e.g a 4xx error, which by default wouldn't be reported.
@@ -42,14 +51,6 @@ export interface ErrorData {
    */
   reportRate?: number
 
-  /**
-   * Sometimes error.message gets "decorated" with extra information
-   * (e.g frontend-lib adds a method, url, etc for all the errors)
-   * `originalMessage` is used to preserve the original `error.message` as it came from the backend.
-   */
-  // originalMessage?: string
-  // use .cause.message instead
-
   /**
    * Can be used by error-reporting tools (e.g Sentry).
    * If fingerprint is defined - it'll be used INSTEAD of default fingerprint of a tool.

package/src/error/error.util.ts

@@ -6,7 +6,7 @@ import type {
   HttpRequestErrorData,
   ErrorLike,
 } from '..'
-import { AppError, _jsonParseIfPossible, _stringifyAny } from '..'
+import { AppError, _jsonParseIfPossible, _stringifyAny, _truncate } from '..'
 
 /**
  * Useful to ensure that error in `catch (err) { ... }`
@@ -54,7 +54,6 @@ export function _anyToErrorObject<DATA_TYPE extends ErrorData = ErrorData>(
 ): ErrorObject<DATA_TYPE> {
   let eo: ErrorObject<DATA_TYPE>
 
-  // if (o instanceof Error) {
   if (_isErrorLike(o)) {
     eo = _errorLikeToErrorObject(o)
   } else {
@@ -88,6 +87,15 @@ export function _anyToErrorObject<DATA_TYPE extends ErrorData = ErrorData>(
 export function _errorLikeToErrorObject<DATA_TYPE extends ErrorData = ErrorData>(
   e: AppError<DATA_TYPE> | Error | ErrorLike,
 ): ErrorObject<DATA_TYPE> {
+  // If it's already an ErrorObject - just return it
+  // AppError satisfies ErrorObject interface
+  // Error does not satisfy (lacks `data`)
+  // UPD: no, we expect a "plain object" here as an output,
+  // because Error classes sometimes have non-enumerable properties (e.g data)
+  if (!(e instanceof Error) && _isErrorObject(e)) {
+    return e as ErrorObject<DATA_TYPE>
+  }
+
   const obj: ErrorObject<DATA_TYPE> = {
     name: e.name,
     message: e.message,
@@ -156,6 +164,64 @@ export function _errorObjectToError<DATA_TYPE extends ErrorData, ERROR_TYPE exte
   return err
 }
 
+export interface ErrorSnippetOptions {
+  /**
+   * Max length of the error line.
+   * Snippet may have multiple lines, one original and one per `cause`.
+   */
+  maxLineLength?: number
+
+  maxLines?: number
+}
+
+// These "common" error classes will not be printed as part of the Error snippet
+const commonErrorClasses = new Set([
+  'Error',
+  'AppError',
+  'AssertionError',
+  'HttpRequestError',
+  'JoiValidationError',
+])
+
+/**
+ * Provides a short semi-user-friendly error message snippet,
+ * that would allow to give a hint to the user what went wrong,
+ * also to developers and CS to distinguish between different errors.
+ *
+ * It's not supposed to have full information about the error, just a small extract from it.
+ */
+export function _errorSnippet(err: any, opt: ErrorSnippetOptions = {}): string {
+  const { maxLineLength = 60, maxLines = 3 } = opt
+  const e = _anyToErrorObject(err)
+
+  const lines = [errorObjectToSnippet(e)]
+
+  let { cause } = e
+
+  while (cause && lines.length < maxLines) {
+    lines.push('Caused by ' + errorObjectToSnippet(cause))
+    cause = cause.cause // insert DiCaprio Inception meme
+  }
+
+  return lines.map(line => _truncate(line, maxLineLength)).join('\n')
+
+  function errorObjectToSnippet(e: ErrorObject): string {
+    // Return snippet if it was already prepared
+    if (e.data.snippet) return e.data.snippet
+
+    // Code already serves the purpose of the snippet, so we can just return it
+    if (e.data.code) return e.data.code
+
+    return [
+      !commonErrorClasses.has(e.name) && e.name,
+      // replace "1+ white space characters" with a single space
+      e.message.replaceAll(/\s+/gm, ' ').trim(),
+    ]
+      .filter(Boolean)
+      .join(': ')
+  }
+}
+
 export function _isBackendErrorResponseObject(o: any): o is BackendErrorResponseObject {
   return _isErrorObject(o?.error)
 }