@naturalcycles/js-lib 14.277.0 → 15.0.1

package/dist-esm/env.js

@@ -1,19 +0,0 @@
-/**
- * Use it to detect SSR/Node.js environment.
- *
- * Will return `true` in Node.js.
- * Will return `false` in the Browser.
- */
-export function isServerSide() {
-    return !isClientSide();
-}
-/**
- * Use it to detect Browser (not SSR/Node) environment.
- *
- * Will return `true` in the Browser.
- * Will return `false` in Node.js.
- */
-export function isClientSide() {
-    // eslint-disable-next-line unicorn/prefer-global-this
-    return typeof window !== 'undefined' && !!window?.document;
-}

package/dist-esm/error/assert.js

@@ -1,122 +0,0 @@
-import { _deepEquals } from '../object/deepEquals';
-import { _stringify } from '../string/stringify';
-import { TS_2000, TS_2500 } from '../zod/zod.shared.schemas';
-import { _isBackendErrorResponseObject, _isErrorObject, AssertionError } from './error.util';
-/**
- * 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 { backendResponseStatusCode: 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.
- */
-export function _assert(condition, // will be evaluated as Boolean
-message, errorData) {
-    if (!condition) {
-        throw new AssertionError(message || 'condition failed', {
-            ...errorData,
-        });
-    }
-}
-/**
- * Like _assert(), but prints more helpful error message.
- * API is similar to Node's assert.equals().
- *
- * Does SHALLOW, but strict equality (===), use _assertDeepEquals() for deep equality.
- */
-export function _assertEquals(actual, expected, message, errorData) {
-    if (actual !== expected) {
-        const msg = message ||
-            ['not equal', `expected: ${_stringify(expected)}`, `got     : ${_stringify(actual)}`]
-                .filter(Boolean)
-                .join('\n');
-        throw new AssertionError(msg, {
-            ...errorData,
-        });
-    }
-}
-/**
- * Like _assert(), but prints more helpful error message.
- * API is similar to Node's assert.deepEquals().
- *
- * Does DEEP equality via _deepEquals()
- */
-export function _assertDeepEquals(actual, expected, message, errorData) {
-    if (!_deepEquals(actual, expected)) {
-        const msg = message ||
-            ['not deeply equal', `expected: ${_stringify(expected)}`, `got     : ${_stringify(actual)}`]
-                .filter(Boolean)
-                .join('\n');
-        throw new AssertionError(msg, {
-            ...errorData,
-        });
-    }
-}
-export function _assertIsError(err, errorClass = Error) {
-    if (!(err instanceof errorClass)) {
-        throw new AssertionError(`Expected to be instanceof ${errorClass.name}, actual typeof: ${typeof err}`);
-    }
-}
-/**
- * Asserts that passed object is indeed an Error of defined ErrorClass.
- * If yes - returns peacefully (with TypeScript assertion).
- * In not - throws (re-throws) that error up.
- */
-export function _assertErrorClassOrRethrow(err, errorClass) {
-    if (!(err instanceof errorClass)) {
-        // re-throw
-        throw err;
-    }
-}
-export function _assertIsErrorObject(obj) {
-    if (!_isErrorObject(obj)) {
-        throw new AssertionError(`Expected to be ErrorObject, actual typeof: ${typeof obj}`);
-    }
-}
-export function _assertIsBackendErrorResponseObject(obj) {
-    if (!_isBackendErrorResponseObject(obj)) {
-        throw new AssertionError(`Expected to be BackendErrorResponseObject, actual typeof: ${typeof obj}`);
-    }
-}
-export function _assertIsString(v, message) {
-    _assertTypeOf(v, 'string', message);
-}
-export function _assertIsNumber(v, message) {
-    _assertTypeOf(v, 'number', message);
-}
-export function _assertTypeOf(v, expectedType, message) {
-    // biome-ignore lint/suspicious/useValidTypeof: ok
-    if (typeof v !== expectedType) {
-        const msg = message || `Expected typeof ${expectedType}, actual typeof: ${typeof v}`;
-        throw new AssertionError(msg);
-    }
-}
-/**
- * Casts an arbitrary number as UnixTimestamp.
- * Right now does not perform any validation (unlike `asUnixTimestamp2000`),
- * but only type casting.
- */
-export function asUnixTimestamp(n) {
-    return n;
-}
-/**
- * Casts an arbitrary number as UnixTimestamp2000.
- * Throws if the number is not inside 2000-01-01 and 2500-01-01 time interval,
- * which would indicate a bug.
- */
-export function asUnixTimestamp2000(n) {
-    if (!n || n < TS_2000 || n > TS_2500) {
-        throw new AssertionError(`Number is not a valid UnixTimestamp2000: ${n}`, {
-            fingerprint: 'asUnixTimestamp2000',
-        });
-    }
-    return n;
-}

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

@@ -1 +0,0 @@
-export {};

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

@@ -1,337 +0,0 @@
-import { isServerSide } from '../env';
-import { _jsonParseIfPossible } from '../string/json.util';
-import { _truncate, _truncateMiddle } from '../string/string.util';
-import { _stringify } from '../string/stringify';
-/**
- * Useful to ensure that error in `catch (err) { ... }`
- * is indeed an Error (and not e.g `string` or `undefined`).
- * 99% of the cases it will be Error already.
- * Becomes more useful since TypeScript 4.4 made `err` of type `unknown` by default.
- *
- * Alternatively, if you're sure it's Error - you can use `_assertIsError(err)`.
- */
-export function _anyToError(o, errorClass = Error, errorData) {
-    let e;
-    if (o instanceof errorClass) {
-        e = o;
-    }
-    else {
-        // If it's an instance of Error, but ErrorClass is something else (e.g AppError) - it'll be "repacked" into AppError
-        const errorObject = _anyToErrorObject(o);
-        e = _errorObjectToError(errorObject, errorClass);
-    }
-    if (errorData) {
-        ;
-        e.data = {
-            ...e.data,
-            ...errorData,
-        };
-    }
-    return e;
-}
-/**
- * Converts "anything" to ErrorObject.
- * Detects if it's HttpErrorResponse, HttpErrorObject, ErrorObject, Error, etc..
- * If object is Error - Error.message will be used.
- * Objects (not Errors) get converted to prettified JSON string (via `_stringify`).
- */
-export function _anyToErrorObject(o, errorData) {
-    let eo;
-    if (_isErrorLike(o)) {
-        eo = _errorLikeToErrorObject(o);
-    }
-    else {
-        o = _jsonParseIfPossible(o);
-        if (_isBackendErrorResponseObject(o)) {
-            eo = o.error;
-        }
-        else if (_isErrorObject(o)) {
-            eo = o;
-        }
-        else if (_isErrorLike(o)) {
-            eo = _errorLikeToErrorObject(o);
-        }
-        else {
-            // Here we are sure it has no `data` property,
-            // so, fair to return `data: {}` in the end
-            // Also we're sure it includes no "error name", e.g no `Error: ...`,
-            // so, fair to include `name: 'Error'`
-            const message = _stringify(o);
-            eo = {
-                name: 'Error',
-                message,
-                data: {}, // empty
-            };
-        }
-    }
-    Object.assign(eo.data, 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,
-        data: { ...e.data }, // empty by default
-    };
-    if (e.stack)
-        obj.stack = e.stack;
-    if (e.cause) {
-        obj.cause = _anyToErrorObject(e.cause);
-    }
-    return obj;
-}
-export function _errorObjectToError(o, errorClass = Error) {
-    if (o instanceof errorClass)
-        return o;
-    // Here we pass constructor values assuming it's AppError or sub-class of it
-    // If not - will be checked at the next step
-    // We cannot check `if (errorClass instanceof AppError)`, only `err instanceof AppError`
-    const { name, cause } = o;
-    const err = new errorClass(o.message, o.data, { name, cause });
-    // name: err.name, // cannot be assigned to a readonly property like this
-    // stack: o.stack, // also readonly e.g in Firefox
-    if (o.stack) {
-        Object.defineProperty(err, 'stack', {
-            value: o.stack,
-        });
-    }
-    if (!(err instanceof AppError)) {
-        // Following actions are only needed for non-AppError-like errors
-        Object.defineProperties(err, {
-            name: {
-                value: name,
-                configurable: true,
-                writable: true,
-            },
-            data: {
-                value: o.data,
-                writable: true,
-                configurable: true,
-                enumerable: false,
-            },
-            cause: {
-                value: cause,
-                writable: true,
-                configurable: true,
-                enumerable: true,
-            },
-        });
-        Object.defineProperty(err.constructor, 'name', {
-            value: name,
-            configurable: true,
-            writable: true,
-        });
-    }
-    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?.error);
-}
-export function _isHttpRequestErrorObject(o) {
-    return !!o && o.name === 'HttpRequestError' && typeof o.data?.requestUrl === 'string';
-}
-/**
- * Note: any instance of AppError is also automatically an ErrorObject
- */
-export function _isErrorObject(o) {
-    return (!!o &&
-        typeof o === 'object' &&
-        typeof o.name === 'string' &&
-        typeof o.message === 'string' &&
-        typeof o.data === 'object');
-}
-export function _isErrorLike(o) {
-    return !!o && typeof o === 'object' && typeof o.name === 'string' && typeof o.message === 'string';
-}
-/**
- * Convenience function to safely add properties to Error's `data` object
- * (even if it wasn't previously existing).
- * Mutates err.
- * Returns err for convenience, so you can re-throw it directly.
- *
- * @example
- *
- * try {} catch (err) {
- *   throw _errorDataAppend(err, {
- *     backendResponseStatusCode: 401,
- *   })
- * }
- */
-export function _errorDataAppend(err, data) {
-    var _a;
-    if (!data)
-        return err;
-    (_a = err).data || (_a.data = {}); // create err.data if it doesn't exist
-    // Using Object.assign instead of ...data to not override err.data's non-enumerable properties
-    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 {
-    /**
-     * Experimental alternative static constructor.
-     */
-    static of(opt) {
-        return new AppError(opt.message, opt.data, {
-            name: opt.name,
-            cause: opt.cause,
-        });
-    }
-    constructor(message, data = {}, opt = {}) {
-        super(message);
-        // Here we default to `this.constructor.name` on Node, but to 'AppError' on the Frontend
-        // because Frontend tends to minify class names, so `constructor.name` is not reliable
-        const { name = isServerSide() ? this.constructor.name : 'AppError', 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, { ...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, { ...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(message) {
-        super(message || 'expected error was not thrown', {}, {
-            name: 'UnexpectedPassError',
-        });
-    }
-}

package/dist-esm/error/errorMode.js

@@ -1,20 +0,0 @@
-/**
- * Allows to define error-controlling behaviour for batch operations.
- *
- * @default is THROW_IMMEDIATELY in most cases
- */
-export var ErrorMode;
-(function (ErrorMode) {
-    /**
-     * Usually a default behaviour, similar as "exit early".
-     */
-    ErrorMode["THROW_IMMEDIATELY"] = "THROW_IMMEDIATELY";
-    /**
-     * Don't throw on errors, but collect them and throw as AggregateError in the end.
-     */
-    ErrorMode["THROW_AGGREGATED"] = "THROW_AGGREGATED";
-    /**
-     * Completely suppress errors, do not aggregate nor throw anything. Resilient mode.
-     */
-    ErrorMode["SUPPRESS"] = "SUPPRESS";
-})(ErrorMode || (ErrorMode = {}));

package/dist-esm/error/try.js

@@ -1,105 +0,0 @@
-import { _stringify } from '../string/stringify';
-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`.
- * Useful e.g. in unit tests.
- *
- * Similar to pTry, but for sync functions.
- *
- * ERR is typed as Error, not `unknown`. While unknown would be more correct,
- * according to recent TypeScript, Error gives more developer convenience.
- * In our code we NEVER throw non-errors.
- * Only possibility of non-error is in the 3rd-party library code, in these cases it
- * can be manually cast to `unknown` for extra safety.
- *
- * @example
- *
- * const [err, v] = _try(() => someFunction())
- * if (err) ...do something...
- * v // go ahead and use v
- */
-export function _try(fn, errorClass) {
-    try {
-        return [null, fn()];
-    }
-    catch (err) {
-        if (errorClass) {
-            _assertErrorClassOrRethrow(err, errorClass);
-        }
-        return [err, null];
-    }
-}
-/**
- * Like _try, but for Promises.
- */
-export async function pTry(promise, errorClass) {
-    try {
-        return [null, await promise];
-    }
-    catch (err) {
-        if (errorClass) {
-            _assertErrorClassOrRethrow(err, errorClass);
-        }
-        return [err, null];
-    }
-}
-/**
- * Calls `fn`, expects is to throw, catches the expected error and returns.
- * If error was NOT thrown - throws UnexpectedPassError instead.
- *
- * If `errorClass` is passed:
- * 1. It automatically infers it's type
- * 2. It does `instanceof` check and throws if wrong Error instance was thrown.
- */
-export function _expectedError(fn, errorClass) {
-    try {
-        fn();
-    }
-    catch (err) {
-        if (errorClass && !(err instanceof errorClass)) {
-            console.warn(`_expectedError expected ${errorClass.constructor.name} but got different error class`);
-            throw err;
-        }
-        return err; // this is expected!
-    }
-    // Unexpected!
-    throw new UnexpectedPassError();
-}
-/**
- * Awaits passed `promise`, expects is to throw (reject), catches the expected error and returns.
- * If error was NOT thrown - throws UnexpectedPassError instead.
- *
- * If `errorClass` is passed:
- * 1. It automatically infers it's type
- * 2. It does `instanceof` check and throws if wrong Error instance was thrown.
- */
-export async function pExpectedError(promise, errorClass) {
-    try {
-        await promise;
-    }
-    catch (err) {
-        if (errorClass && !(err instanceof errorClass)) {
-            console.warn(`pExpectedError expected ${errorClass.constructor.name} but got different error class`);
-            throw err;
-        }
-        return err; // this is expected!
-    }
-    // Unexpected!
-    throw new UnexpectedPassError();
-}
-/**
- * Shortcut function to simplify error snapshot-matching in tests.
- */
-export async function pExpectedErrorString(promise, errorClass) {
-    const err = await pExpectedError(promise, errorClass);
-    return _stringify(err);
-}
-/**
- * Shortcut function to simplify error snapshot-matching in tests.
- */
-export function _expectedErrorString(fn, errorClass) {
-    const err = _expectedError(fn, errorClass);
-    return _stringify(err);
-}

package/dist-esm/error/tryCatch.js

@@ -1,41 +0,0 @@
-import { _anyToError, _since } from '../index';
-/**
- * Decorates a function with "try/catch", so it'll never reject/throw.
- * Only applies to async functions (or, turns sync function into async).
- *
- * Allows to pass onError callback.
- *
- * @experimental
- */
-export function _tryCatch(fn, opt = {}) {
-    const { onError, logError = true, logSuccess = false, logger = console } = opt;
-    const fname = fn.name || 'anonymous';
-    return async function (...args) {
-        const started = Date.now();
-        try {
-            const r = await fn.apply(this, args);
-            if (logSuccess) {
-                logger.log(`tryCatch.${fname} succeeded in ${_since(started)}`);
-            }
-            return r;
-        }
-        catch (err) {
-            if (logError) {
-                logger.warn(`tryCatch.${fname} error in ${_since(started)}:`, err);
-            }
-            if (onError) {
-                try {
-                    return await onError(_anyToError(err));
-                }
-                catch { }
-            }
-            // returns undefined, but doesn't rethrow
-        }
-    };
-}
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export const _TryCatch = (opt = {}) => (_target, _key, descriptor) => {
-    const originalFn = descriptor.value;
-    descriptor.value = _tryCatch(originalFn, opt);
-    return descriptor;
-};

package/dist-esm/form.util.js

@@ -1,16 +0,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.
- */
-export function objectToFormData(obj = {}) {
-    const fd = new FormData();
-    for (const [k, v] of Object.entries(obj)) {
-        fd.append(k, v);
-    }
-    return fd;
-}
-export function formDataToObject(formData) {
-    return Object.fromEntries(formData);
-}