@naturalcycles/js-lib 14.171.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-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.171.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)
 }