Error

_tryCatch

Wraps/decorates a passed function with "try/catch", so it never throws, but logs the error (if occured).

const someDangerousFunction = () => { ... }

const fn = _tryCatch(someDangerousFunction)

fn()
// will log on error, but never throw

Allows to pass onError() function hook, that will be called on error.

ErrorObject

Standartized "Error object" that contains arbitrary data object that can hold additional data.

This data object is defined as a Generic type to ErrorObject, so, e.g. HttpError has HttpErrorData, which has a mandatory httpStatusCode: number property.

Usage example of that:

.catch((err: HttpErrorObject) => {
  console.log(err.data.httpStatusCode)
})

AppError

The most basic implementation of an Error that complies with ErrorObject specification. Difference is that ErrorObject is purely a TypeScript interface (around any JS object), but AppError is a sub-class of Error. So, with AppError you can do if (err instanceof AppError) ....

Because AppError implements ErrorObject, it guarantees an err.data object.

This basic contract allows to establish a standartized interface between the Frontend (in frontend-lib) and Backend (in backend-lib) and implement error-handling more efficiently.

HttpError

Subclass of AppError that has some additional properties inside data, namely: httpStatusCode: number.

HttpErrorResponse

This is a standartized "Error response from the Backend" (as implemented in backend-lib). You can check/assert it with _isHttpErrorResponse, and then have all the guarantees and types about the containing error object.

Handling these type of errors is done "automatically" in getKy of the frontend-lib, and in getGot of the backend-lib.

_anyToError

Cast any to Error.

_errorToErrorObject

Cast Error to ErrorObject.

_isHttpErrorResponse

Assert if provided value: any is a HttpErrorResponse.

_isHttpErrorObject

Assert if provided value: any is a HttpErrorObject (an HttpError, same as AppError<HttpErrorData>).

_isErrorObject

Assert if provided value: any is an ErrorObject.

_assert

Asserts that a boolean condition is truthy, otherwise throws an Error.

Evaluates the condition (casts it to Boolean). Expects it to be truthy, otherwise throws AppError.

Should be used NOT for "expected" / user-facing errors, but vice-versa - for completely unexpected and 100% buggy "should never happen" cases.

It'll result in http 500 on the server (cause that's the right code for "unexpected" errors). Pass { httpStatusCode: x } at errorData argument to override the http code (will be picked up by backend-lib).

API is similar to Node's assert(), except:

1. Throws js-lib's AppError
2. Has a default message, if not provided

Since 2024-07-10 it no longer sets userFriendly: true by default.

function run(err: any) {
  _assert(err instanceof AppError)
  // from here TypeScript will know that `err instanceof AppError === true`, or `err: AppError`

  // Example with custom error message:
  _assert(err instanceof AppError, 'error should be of type AppError')
}

_assertEquals

Similar to _assert, but allows to provide 2 values (first 2 arguments) and throws if they are NOT equal.

Does a shallow equality check (!==), use _assertDeepEquals if you need a deep-check.

_assertDeepEquals

Similar to _assertEquals, but does a deep assertion (using _deepEquals).

_assertIsError

Asserts that passed value is instanceof Error.

_assertsIsTypeOf

Asserts that typeof value matches expected type.

_assertsIsString

Asserts that typeof value === 'string

_assertsIsNumber

Asserts that typeof value === 'number

_try

Calls a function, returns a Tuple of [error, value]. Allows to write shorter code that avoids try/catch. Useful e.g. in unit tests.

Similar to pTry, but for sync functions.

const [err, v] = _try(() => someFunction())

pTry

Loosely inspired by await-to-js.

Similar to _try, but for promises.

Async/await wrapper for easy error handling. Wraps async/await calls in try catch blocks and returns a tuple containing the error or the results of the promise

interface ServerResponse {
  test: number
}

interface CustomError {
  code: number
  data: {
    title: string
    body: string
  }
}

const p = Promise.resolve({ test: 123 })

const [err, result] = await pTuple<ServerResponse, CustomError>(p)