@naturalcycles/js-lib 14.171.0 → 14.173.0

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

@@ -1,4 +1,4 @@
-import { AppError, _jsonParseIfPossible, _stringifyAny } from '..';
+import { _jsonParseIfPossible, _stringifyAny, _truncate, _truncateMiddle } 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);
 }
@@ -159,3 +207,112 @@ export function _errorDataAppend(err, data) {
     err.data = Object.assign(Object.assign({}, err.data), data);
     return err;
 }
+/**
+ * Base class for all our (not system) errors.
+ *
+ * message - "technical" message. Frontend decides to show it or not.
+ * data - optional "any" payload.
+ * data.userFriendly - if present, will be displayed to the User as is.
+ *
+ * Based on: https://medium.com/@xpl/javascript-deriving-from-error-properly-8d2f8f315801
+ */
+export class AppError extends Error {
+    constructor(message, data = {}, opt = {}) {
+        super(message);
+        const { name = this.constructor.name, cause } = opt;
+        Object.defineProperties(this, {
+            name: {
+                value: name,
+                configurable: true,
+                writable: true,
+            },
+            data: {
+                value: data,
+                writable: true,
+                configurable: true,
+                enumerable: false,
+            },
+        });
+        if (cause) {
+            Object.defineProperty(this, 'cause', {
+                value: _anyToErrorObject(cause),
+                writable: true,
+                configurable: true,
+                enumerable: true, // unlike standard - setting it to true for "visibility"
+            });
+        }
+        // this is to allow changing this.constuctor.name to a non-minified version
+        Object.defineProperty(this.constructor, 'name', {
+            value: name,
+            configurable: true,
+            writable: true,
+        });
+        // todo: check if it's needed at all!
+        // if (Error.captureStackTrace) {
+        //   Error.captureStackTrace(this, this.constructor)
+        // } else {
+        //   Object.defineProperty(this, 'stack', {
+        //     value: new Error().stack, // eslint-disable-line unicorn/error-message
+        //     writable: true,
+        //     configurable: true,
+        //   })
+        // }
+    }
+}
+/**
+ * Error that is thrown when Http Request was made and returned an error.
+ * Thrown by, for example, Fetcher.
+ *
+ * On the Frontend this Error class represents the error when calling the API,
+ * contains all the necessary request and response information.
+ *
+ * On the Backend, similarly, it represents the error when calling some 3rd-party API
+ * (backend-to-backend call).
+ * On the Backend it often propagates all the way to the Backend error handler,
+ * where it would be wrapped in BackendErrorResponseObject.
+ *
+ * Please note that `ErrorData.backendResponseStatusCode` is NOT exactly the same as
+ * `HttpRequestErrorData.responseStatusCode`.
+ * E.g 3rd-party call may return 401, but our Backend will still wrap it into an 500 error
+ * (by default).
+ */
+export class HttpRequestError extends AppError {
+    constructor(message, data, opt) {
+        if (data.response) {
+            Object.defineProperty(data, 'response', {
+                enumerable: false,
+            });
+        }
+        super(message, data, Object.assign(Object.assign({}, opt), { name: 'HttpRequestError' }));
+    }
+}
+export class AssertionError extends AppError {
+    constructor(message, data) {
+        super(message, data, { name: 'AssertionError' });
+    }
+}
+export class JsonParseError extends AppError {
+    constructor(data) {
+        const message = ['Failed to parse', data.text && _truncateMiddle(data.text, 200)]
+            .filter(Boolean)
+            .join(': ');
+        super(message, data, { name: 'JsonParseError' });
+    }
+}
+export class TimeoutError extends AppError {
+    constructor(message, data, opt) {
+        super(message, data, Object.assign(Object.assign({}, opt), { name: 'TimeoutError' }));
+    }
+}
+/**
+ * It is thrown when Error was expected, but didn't happen
+ * ("pass" happened instead).
+ * "Pass" means "no error".
+ */
+export class UnexpectedPassError extends AppError {
+    constructor() {
+        super('expected error was not thrown', {}, {
+            name: 'UnexpectedPassError',
+        });
+    }
+}

package/dist-esm/error/try.js

@@ -1,6 +1,6 @@
 import { _stringifyAny } from '../string/stringifyAny';
-import { AppError } from './app.error';
 import { _assertErrorClassOrRethrow } from './assert';
+import { UnexpectedPassError } from './error.util';
 /**
  * Calls a function, returns a Tuple of [error, value].
  * Allows to write shorter code that avoids `try/catch`.
@@ -45,18 +45,6 @@ export async function pTry(promise, errorClass) {
         return [err, null];
     }
 }
-/**
- * It is thrown when Error was expected, but didn't happen
- * ("pass" happened instead).
- * "Pass" means "no error".
- */
-export class UnexpectedPassError extends AppError {
-    constructor() {
-        super('expected error was not thrown', {}, {
-            name: 'UnexpectedPassError',
-        });
-    }
-}
 /**
  * Calls `fn`, expects is to throw, catches the expected error and returns.
  * If error was NOT thrown - throws UnexpectedPassError instead.

package/dist-esm/http/fetcher.js

@@ -3,12 +3,11 @@
 var _a;
 import { isServerSide } from '../env';
 import { _assertErrorClassOrRethrow } from '../error/assert';
-import { _anyToError, _anyToErrorObject, _errorLikeToErrorObject } from '../error/error.util';
-import { HttpRequestError } from '../error/httpRequestError';
+import { _anyToError, _anyToErrorObject, _errorLikeToErrorObject, HttpRequestError, TimeoutError, } from '../error/error.util';
 import { _clamp } from '../number/number.util';
 import { _filterNullishValues, _filterUndefinedValues, _mapKeys, _merge, _omit, _pick, } from '../object/object.util';
 import { pDelay } from '../promise/pDelay';
-import { pTimeout, TimeoutError } from '../promise/pTimeout';
+import { pTimeout } from '../promise/pTimeout';
 import { _jsonParse, _jsonParseIfPossible } from '../string/json.util';
 import { _stringifyAny } from '../string/stringifyAny';
 import { _ms, _since } from '../time/time.util';

package/dist-esm/index.js

@@ -14,16 +14,13 @@ export * from './decorators/memoFn';
 export * from './decorators/memoFnAsync';
 export * from './decorators/retry.decorator';
 export * from './decorators/timeout.decorator';
-export * from './error/app.error';
 export * from './error/assert';
 export * from './enum.util';
 export * from './error/error.model';
 export * from './error/error.util';
 export * from './error/errorMode';
-export * from './error/httpRequestError';
 export * from './error/try';
 export * from './error/tryCatch';
-export * from './error/jsonParseError';
 export * from './json-schema/from-data/generateJsonSchemaFromData';
 export * from './json-schema/jsonSchema.cnst';
 export * from './json-schema/jsonSchema.model';

package/dist-esm/promise/pTimeout.js

@@ -1,10 +1,4 @@
-import { AppError } from '../error/app.error';
-import { _errorDataAppend } from '../error/error.util';
-export class TimeoutError extends AppError {
-    constructor(message, data, opt) {
-        super(message, data, Object.assign(Object.assign({}, opt), { name: 'TimeoutError' }));
-    }
-}
+import { _errorDataAppend, TimeoutError } from '../error/error.util';
 /**
  * Decorates a Function with a timeout.
  * Returns a decorated Function.

package/dist-esm/string/json.util.js

@@ -1,4 +1,4 @@
-import { JsonParseError } from '../error/jsonParseError';
+import { JsonParseError } from '../error/error.util';
 // const possibleJsonStartTokens = ['{', '[', '"']
 const DETECT_JSON = /^\s*[{["\-\d]/;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.171.0",
+  "version": "14.173.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/assert.ts

@@ -1,6 +1,5 @@
 import type { ErrorData, ErrorObject } from '..'
-import { _deepEquals, _isErrorObject, _stringifyAny, Class } from '..'
-import { AppError } from './app.error'
+import { _deepEquals, _isErrorObject, _stringifyAny, AssertionError, Class } from '..'
 
 /**
  * Evaluates the `condition` (casts it to Boolean).
@@ -150,9 +149,3 @@ export function _assertTypeOf<T>(v: any, expectedType: string, message?: string)
     })
   }
 }
-
-export class AssertionError extends AppError {
-  constructor(message: string, data?: ErrorData) {
-    super(message, data, { name: 'AssertionError' })
-  }
-}

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 { _jsonParseIfPossible, _stringifyAny, _truncate, _truncateMiddle } 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)
 }
@@ -206,3 +272,165 @@ export function _errorDataAppend<ERR>(err: ERR, data?: ErrorData): ERR {
 
   return err
 }
+
+/**
+ * Base class for all our (not system) errors.
+ *
+ * message - "technical" message. Frontend decides to show it or not.
+ * data - optional "any" payload.
+ * data.userFriendly - if present, will be displayed to the User as is.
+ *
+ * Based on: https://medium.com/@xpl/javascript-deriving-from-error-properly-8d2f8f315801
+ */
+export class AppError<DATA_TYPE extends ErrorData = ErrorData> extends Error {
+  data!: DATA_TYPE
+
+  /**
+   * `cause` here is normalized to be an ErrorObject
+   */
+  override cause?: ErrorObject
+
+  constructor(message: string, data = {} as DATA_TYPE, opt: AppErrorOptions = {}) {
+    super(message)
+    const { name = this.constructor.name, cause } = opt
+
+    Object.defineProperties(this, {
+      name: {
+        value: name,
+        configurable: true,
+        writable: true,
+      },
+      data: {
+        value: data,
+        writable: true,
+        configurable: true,
+        enumerable: false,
+      },
+    })
+
+    if (cause) {
+      Object.defineProperty(this, 'cause', {
+        value: _anyToErrorObject(cause),
+        writable: true,
+        configurable: true,
+        enumerable: true, // unlike standard - setting it to true for "visibility"
+      })
+    }
+
+    // this is to allow changing this.constuctor.name to a non-minified version
+    Object.defineProperty(this.constructor, 'name', {
+      value: name,
+      configurable: true,
+      writable: true,
+    })
+
+    // todo: check if it's needed at all!
+    // if (Error.captureStackTrace) {
+    //   Error.captureStackTrace(this, this.constructor)
+    // } else {
+    //   Object.defineProperty(this, 'stack', {
+    //     value: new Error().stack, // eslint-disable-line unicorn/error-message
+    //     writable: true,
+    //     configurable: true,
+    //   })
+    // }
+  }
+}
+
+/**
+ * Extra options for AppError constructor.
+ */
+export interface AppErrorOptions {
+  /**
+   * Overrides Error.name and Error.constructor.name
+   */
+  name?: string
+
+  /**
+   * Sets Error.cause.
+   * It is transformed with _anyToErrorObject()
+   */
+  cause?: any
+}
+
+/**
+ * Error that is thrown when Http Request was made and returned an error.
+ * Thrown by, for example, Fetcher.
+ *
+ * On the Frontend this Error class represents the error when calling the API,
+ * contains all the necessary request and response information.
+ *
+ * On the Backend, similarly, it represents the error when calling some 3rd-party API
+ * (backend-to-backend call).
+ * On the Backend it often propagates all the way to the Backend error handler,
+ * where it would be wrapped in BackendErrorResponseObject.
+ *
+ * Please note that `ErrorData.backendResponseStatusCode` is NOT exactly the same as
+ * `HttpRequestErrorData.responseStatusCode`.
+ * E.g 3rd-party call may return 401, but our Backend will still wrap it into an 500 error
+ * (by default).
+ */
+export class HttpRequestError extends AppError<HttpRequestErrorData> {
+  constructor(message: string, data: HttpRequestErrorData, opt?: AppErrorOptions) {
+    if (data.response) {
+      Object.defineProperty(data, 'response', {
+        enumerable: false,
+      })
+    }
+
+    super(message, data, { ...opt, name: 'HttpRequestError' })
+  }
+
+  /**
+   * Cause is strictly-defined for HttpRequestError,
+   * so it always has a cause.
+   * (for dev convenience)
+   */
+  override cause!: ErrorObject
+}
+
+export class AssertionError extends AppError {
+  constructor(message: string, data?: ErrorData) {
+    super(message, data, { name: 'AssertionError' })
+  }
+}
+
+export interface JsonParseErrorData extends ErrorData {
+  /**
+   * Original text that failed to get parsed.
+   */
+  text?: string
+}
+
+export class JsonParseError extends AppError<JsonParseErrorData> {
+  constructor(data: JsonParseErrorData) {
+    const message = ['Failed to parse', data.text && _truncateMiddle(data.text, 200)]
+      .filter(Boolean)
+      .join(': ')
+
+    super(message, data, { name: 'JsonParseError' })
+  }
+}
+
+export class TimeoutError extends AppError {
+  constructor(message: string, data?: ErrorData, opt?: AppErrorOptions) {
+    super(message, data, { ...opt, name: 'TimeoutError' })
+  }
+}
+
+/**
+ * It is thrown when Error was expected, but didn't happen
+ * ("pass" happened instead).
+ * "Pass" means "no error".
+ */
+export class UnexpectedPassError extends AppError {
+  constructor() {
+    super(
+      'expected error was not thrown',
+      {},
+      {
+        name: 'UnexpectedPassError',
+      },
+    )
+  }
+}

package/src/error/try.ts

@@ -1,8 +1,8 @@
 import { _stringifyAny } from '../string/stringifyAny'
 import type { Class } from '../typeFest'
 import type { AnyFunction, ErrorDataTuple } from '../types'
-import { AppError } from './app.error'
 import { _assertErrorClassOrRethrow } from './assert'
+import { UnexpectedPassError } from './error.util'
 
 /**
  * Calls a function, returns a Tuple of [error, value].
@@ -55,23 +55,6 @@ export async function pTry<T, ERR extends Error = Error>(
   }
 }
 
-/**
- * It is thrown when Error was expected, but didn't happen
- * ("pass" happened instead).
- * "Pass" means "no error".
- */
-export class UnexpectedPassError extends AppError {
-  constructor() {
-    super(
-      'expected error was not thrown',
-      {},
-      {
-        name: 'UnexpectedPassError',
-      },
-    )
-  }
-}
-
 /**
  * Calls `fn`, expects is to throw, catches the expected error and returns.
  * If error was NOT thrown - throws UnexpectedPassError instead.

package/src/http/fetcher.ts

@@ -4,8 +4,13 @@
 import { isServerSide } from '../env'
 import { _assertErrorClassOrRethrow } from '../error/assert'
 import { ErrorLike, ErrorObject } from '../error/error.model'
-import { _anyToError, _anyToErrorObject, _errorLikeToErrorObject } from '../error/error.util'
-import { HttpRequestError } from '../error/httpRequestError'
+import {
+  _anyToError,
+  _anyToErrorObject,
+  _errorLikeToErrorObject,
+  HttpRequestError,
+  TimeoutError,
+} from '../error/error.util'
 import { _clamp } from '../number/number.util'
 import {
   _filterNullishValues,
@@ -16,7 +21,7 @@ import {
   _pick,
 } from '../object/object.util'
 import { pDelay } from '../promise/pDelay'
-import { pTimeout, TimeoutError } from '../promise/pTimeout'
+import { pTimeout } from '../promise/pTimeout'
 import { _jsonParse, _jsonParseIfPossible } from '../string/json.util'
 import { _stringifyAny } from '../string/stringifyAny'
 import { _ms, _since } from '../time/time.util'

package/src/index.ts

@@ -14,16 +14,13 @@ export * from './decorators/memoFn'
 export * from './decorators/memoFnAsync'
 export * from './decorators/retry.decorator'
 export * from './decorators/timeout.decorator'
-export * from './error/app.error'
 export * from './error/assert'
 export * from './enum.util'
 export * from './error/error.model'
 export * from './error/error.util'
 export * from './error/errorMode'
-export * from './error/httpRequestError'
 export * from './error/try'
 export * from './error/tryCatch'
-export * from './error/jsonParseError'
 export * from './json-schema/from-data/generateJsonSchemaFromData'
 export * from './json-schema/jsonSchema.cnst'
 export * from './json-schema/jsonSchema.model'