@hg-ts/exception 0.5.17 → 0.5.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hg-ts/exception",
-  "version": "0.5.17",
+  "version": "0.5.19",
   "main": "dist/index.js",
   "type": "module",
   "exports": {
@@ -18,10 +18,10 @@
     "test:dev": "vitest watch"
   },
   "devDependencies": {
-    "@hg-ts-config/typescript": "0.5.17",
-    "@hg-ts/linter": "0.5.17",
-    "@hg-ts/tests": "0.5.17",
-    "@hg-ts/types": "0.5.17",
+    "@hg-ts-config/typescript": "0.5.19",
+    "@hg-ts/linter": "0.5.19",
+    "@hg-ts/tests": "0.5.19",
+    "@hg-ts/types": "0.5.19",
     "@types/node": "22.19.1",
     "@vitest/coverage-v8": "4.0.14",
     "eslint": "9.18.0",

package/src/consts.ts

@@ -0,0 +1 @@
+export const SOURCE_MAP_ENABLED = !!(new Error().stack?.includes('->'));

package/src/exception.factory.ts

@@ -0,0 +1,41 @@
+import {
+	AggregateErrorException,
+	BaseException,
+	ErrorException,
+	ForbiddenException,
+	InvalidInputException,
+	JSONBaseException,
+	NotImplementedException,
+	UnknownException,
+	WillNeverHappenedException,
+} from './exceptions/index.js';
+
+export class ExceptionFactory {
+	private constructor() {}
+
+	public static fromJson<T extends JSONBaseException>(json: T, ctorList: Class<BaseException, any[]>[]): BaseException {
+		const ctorToMap = [
+			...ctorList,
+			AggregateErrorException,
+			ErrorException,
+			ForbiddenException,
+			InvalidInputException,
+			NotImplementedException,
+			UnknownException,
+			WillNeverHappenedException,
+		];
+		for (const ctor of ctorToMap) {
+			const { name, ...exceptionData } = json;
+			if (ctor.name === name) {
+				const exception = Object.create(ctor.prototype);
+
+				Object.assign(exception, exceptionData);
+				Object.assign(exception, { serialized: json });
+
+				return exception;
+			}
+		}
+
+		throw new InvalidInputException(`Exception constructor with name "${json.name}" not passed`);
+	}
+}

package/src/exceptions/aggregate-error.exception.ts

@@ -0,0 +1,26 @@
+import { BaseAggregateException } from './base.aggregate.exception.js';
+import { BaseException } from './base.exception.js';
+
+export class AggregateErrorException extends BaseAggregateException {
+	public constructor(error: AggregateError) {
+		const { errors } = error;
+
+		super(
+			errors
+				.map(error => {
+					if (error instanceof AggregateError) {
+						BaseAggregateException.fromError(error);
+					}
+					if (error instanceof Error) {
+						return BaseException.fromError(error);
+					}
+
+					return null;
+				})
+				.filter((exception): exception is BaseException => exception !== null),
+			error.message,
+		);
+
+		(this as any).stack = error.stack;
+	}
+}

package/src/exceptions/base.aggregate.exception.ts

@@ -0,0 +1,51 @@
+import { AggregateErrorException } from './aggregate-error.exception.js';
+import {
+	BaseException,
+	ExceptionOptions,
+	JSONBaseException,
+	PAD_COUNT_PER_DEPTH,
+} from './base.exception.js';
+
+export type JSONBaseAggregateException = Omit<JSONBaseException, 'cause'> & {
+	exceptions: JSONBaseException[];
+};
+
+export type BaseAggregateExceptionOptions = Omit<ExceptionOptions, 'cause'>;
+
+export abstract class BaseAggregateException extends BaseException {
+	public readonly exceptions: BaseException[];
+
+	protected constructor(
+		exceptions: BaseException[],
+		message: string,
+		options?: BaseAggregateExceptionOptions,
+	) {
+		super(message, options);
+
+		this.exceptions = exceptions;
+	}
+
+	public override toJSON(): JSONBaseAggregateException {
+		const baseJson = super.toJSON();
+
+		return {
+			...baseJson,
+			exceptions: this.exceptions.map(exception => exception.toJSON()),
+		};
+	}
+
+	public static override fromError(error: AggregateError): BaseAggregateException {
+		return new AggregateErrorException(error);
+	}
+
+	protected override injectBeforeStack(padCount: number): string[] {
+		const innerExceptionsInfo = this.exceptions
+			.map(exception => exception['getStringifyFirstLine']())
+			.map(line => BaseException.padLine(line, padCount));
+
+		return [
+			BaseException.padLine('Aggregated exceptions info:', padCount - PAD_COUNT_PER_DEPTH),
+			...innerExceptionsInfo,
+		];
+	}
+}

package/src/exceptions/base.exception.ts

@@ -0,0 +1,139 @@
+import * as os from 'os';
+import {
+	inspect,
+	InspectOptionsStylized,
+} from 'util';
+
+import { StackTraceFormatter } from '../utils/index.js';
+import { ErrorException } from './error.exception.js';
+
+export type JSONBaseException = {
+	name: string;
+	code: Nullable<number>;
+	message: string;
+	stack: string[];
+	cause?: JSONBaseException;
+};
+
+export type ExceptionOptions = {
+	cause?: BaseException | undefined;
+	code?: number | undefined;
+};
+
+export const PAD_COUNT_PER_DEPTH = 4;
+
+export abstract class BaseException extends Error {
+	public readonly code: Nullable<number> = null;
+	public override readonly stack: string;
+	public override readonly message: string;
+	public override readonly cause?: BaseException;
+	private serialized: Nullable<JSONBaseException> = null;
+
+	public constructor(message: string, codeOrOptions: ExceptionOptions = {}) {
+		super(message);
+		this.message = message;
+
+
+		if (codeOrOptions.cause) {
+			this.cause = codeOrOptions.cause;
+		}
+		if (codeOrOptions.code) {
+			this.code = codeOrOptions.code;
+		}
+
+		Error.captureStackTrace(this, this.getCtor());
+	}
+
+	public override get name(): string {
+		const { name } = this.getCtor();
+
+		return name;
+	}
+
+	public toJSON(): JSONBaseException {
+		if (this.serialized === null) {
+			const { name, message, stack, code, cause } = this;
+
+			this.serialized = {
+				name,
+				code,
+				message,
+				stack: StackTraceFormatter.format(stack, this.name),
+			};
+
+			if (cause) {
+				this.serialized.cause = cause.toJSON();
+			}
+		}
+
+		return this.serialized;
+	}
+
+	public override toString(padCount = PAD_COUNT_PER_DEPTH): string {
+		const { stack } = this.toJSON();
+		const formattedStack = stack.map(line => BaseException.padLine(line, padCount));
+
+		const errorLines = [
+			this.getStringifyFirstLine(),
+			...this.injectBeforeStack(padCount + PAD_COUNT_PER_DEPTH),
+			...formattedStack,
+		];
+
+		return errorLines.join(os.EOL);
+	}
+
+	// eslint-disable-next-line @typescript/unbound-method
+	public [inspect.custom](_depth: Nullable<number>, { stylize }: InspectOptionsStylized): string {
+		return stylize(this.toString(), 'regexp');
+	}
+
+	public isFromNextTick(): boolean {
+		const lastLine = this.getLastStackLine();
+
+		return lastLine.includes('processTicksAndRejections');
+	}
+
+	public isFromImmediate(): boolean {
+		const lastLine = this.getLastStackLine();
+
+		return lastLine.includes('Immediate._onImmediate');
+	}
+
+	public isFromTimer(): boolean {
+		const lastLine = this.getLastStackLine();
+
+		return lastLine.includes('Timeout._onTimeout');
+	}
+
+	public static fromError(error: Error): BaseException {
+		return new ErrorException(error);
+	}
+
+	protected getCtor(): Function {
+		return Object.getPrototypeOf(this)!.constructor;
+	}
+
+	protected getStringifyFirstLine(): string {
+		const { name, code, message } = this.toJSON();
+
+		return `${name}${code === null ? '' : ` [code: ${code}]`}: ${message}`;
+	}
+
+	protected injectBeforeStack(padCount: number): string[] {
+		if (this.cause) {
+			return [BaseException.padLine(this.cause.getStringifyFirstLine(), padCount)];
+		}
+
+		return [];
+	}
+
+	protected static padLine(line: string, padCount: number): string {
+		return `${' '.repeat(padCount)}${line}`;
+	}
+
+	private getLastStackLine(): string {
+		const { stack } = this.toJSON();
+
+		return stack[stack.length - 1] ?? '';
+	}
+}

package/src/exceptions/error.exception.ts

@@ -0,0 +1,16 @@
+import { BaseException } from './base.exception.js';
+
+export class ErrorException extends BaseException {
+	public constructor(error: Error) {
+		const { cause } = error as any;
+
+		super(error.message, {
+			cause: cause instanceof Error
+				? new ErrorException(cause)
+				// eslint-disable-next-line no-undefined
+				: undefined,
+		});
+
+		(this as any).stack = error.stack;
+	}
+}

package/src/exceptions/forbidden.exception.ts

@@ -0,0 +1,3 @@
+import { BaseException } from './base.exception.js';
+
+export class ForbiddenException extends BaseException {}

package/src/exceptions/index.ts

@@ -0,0 +1,12 @@
+// Error exceptions must be imported before base exceptions because of cyclical imports
+export * from './error.exception.js';
+export * from './aggregate-error.exception.js';
+
+export * from './base.exception.js';
+export * from './base.aggregate.exception.js';
+
+export * from './unknown.exception.js';
+export * from './not-implemented.exception.js';
+export * from './will-never-happened.exception.js';
+export * from './forbidden.exception.js';
+export * from './invalid-input.exception.js';

package/src/exceptions/invalid-input.exception.ts

@@ -0,0 +1,3 @@
+import { BaseException } from './base.exception.js';
+
+export class InvalidInputException extends BaseException {}

package/src/exceptions/not-implemented.exception.ts

@@ -0,0 +1,7 @@
+import { BaseException } from './base.exception.js';
+
+export class NotImplementedException extends BaseException {
+	public constructor() {
+		super('Not implemented');
+	}
+}

package/src/exceptions/unknown.exception.ts

@@ -0,0 +1,7 @@
+import { BaseException } from './base.exception.js';
+
+export class UnknownException extends BaseException {
+	public constructor(message: string) {
+		super(message);
+	}
+}

package/src/exceptions/will-never-happened.exception.ts

@@ -0,0 +1,7 @@
+import { BaseException } from './base.exception.js';
+
+export class WillNeverHappenedException extends BaseException {
+	public constructor(message: string) {
+		super(message);
+	}
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './exceptions/index.js';
+export * from './exception.factory.js';

package/src/tests/serialization.test.ts

@@ -0,0 +1,120 @@
+import {
+	Describe,
+	expect,
+	Suite,
+	Test,
+} from '@hg-ts/tests';
+import {
+	BaseAggregateException,
+	BaseException,
+	ErrorException,
+} from '../exceptions/index.js';
+import { TestAggregateException } from './test.aggregate-exception.js';
+import { TestException } from './test.exception.js';
+
+@Describe()
+export class SerializationTestSuite extends Suite {
+	@Test()
+	public async commonTest(): Promise<void> {
+		const message = 'Test message';
+		const exception = new TestException(message);
+
+		expect(exception).toBeInstanceOf(Error);
+		expect(exception).toBeInstanceOf(BaseException);
+		expect(exception).toBeInstanceOf(TestException);
+		expect(exception.message).toEqual(message);
+		expect(exception.code).toBeNull();
+		expect(exception.toJSON().name).toEqual(TestException.name);
+		expect(exception.toJSON().stack).toBeInstanceOf(Array);
+		expect(exception.toJSON().stack).not.toEqual([]);
+	}
+
+	@Test()
+	public async baseExceptionFromError(): Promise<void> {
+		const message = 'Test message';
+		const error = new Error(message);
+		const exception = BaseException.fromError(error);
+
+		expect(exception).toBeInstanceOf(Error);
+		expect(exception).toBeInstanceOf(BaseException);
+		expect(exception).toBeInstanceOf(ErrorException);
+		expect(exception.message).toEqual(message);
+		expect(exception.code).toBeNull();
+		expect(exception.toJSON().stack).toBeInstanceOf(Array);
+		expect(exception.toJSON().stack).not.toEqual([]);
+	}
+
+	@Test()
+	public async aggregateExceptionTest(): Promise<void> {
+		const message = 'Test aggregate message';
+		const exception = new TestAggregateException(message);
+
+		expect(exception).toBeInstanceOf(Error);
+		expect(exception).toBeInstanceOf(BaseException);
+		expect(exception).toBeInstanceOf(BaseAggregateException);
+		expect(exception).toBeInstanceOf(TestAggregateException);
+
+		expect(exception.message).toEqual(message);
+		expect(exception.code).toBeNull();
+
+		expect(exception.exceptions).toBeInstanceOf(Array);
+		expect(exception.exceptions).toHaveLength(3);
+	}
+
+	@Test()
+	public async syncStackTest(): Promise<void> {
+		const { stack } = new TestException('Test message').toJSON();
+
+		expect(stack[0]!.startsWith(`at ${this.constructor.name}.syncStackTest`)).toBeTruthy();
+	}
+
+	@Test()
+	public async isFromNextTickTest(): Promise<void> {
+		return new Promise<void>(resolve => {
+			process.nextTick(() => {
+				const exception = new TestException('Test message');
+
+				expect(exception.isFromNextTick()).toBeTruthy();
+				resolve();
+			});
+		});
+	}
+
+	@Test()
+	public async isFromImmediateTest(): Promise<void> {
+		return new Promise<void>(resolve => {
+			setImmediate(() => {
+				const exception = new TestException('Test message');
+
+				expect(exception.isFromImmediate()).toBeTruthy();
+				resolve();
+			});
+		});
+	}
+
+	@Test()
+	public async fromTimeoutTest(): Promise<void> {
+		return new Promise<void>(resolve => {
+			setTimeout(() => {
+				const exception = new TestException('Test message');
+
+				expect(exception.isFromTimer()).toBeTruthy();
+				resolve();
+			}, 0);
+		});
+	}
+
+	@Test()
+	public async fromIntervalTest(): Promise<void> {
+		let interval: NodeJS.Timeout;
+		return new Promise<void>(resolve => {
+			interval = setInterval(() => {
+				const exception = new TestException('Test message');
+
+				expect(exception.isFromTimer()).toBeTruthy();
+				clearInterval(interval);
+				resolve();
+			}, 0);
+		});
+	}
+}

package/src/tests/test.aggregate-exception.ts

@@ -0,0 +1,16 @@
+import { BaseAggregateException } from '../exceptions/index.js';
+import { TestException } from './test.exception.js';
+
+export class TestAggregateException extends BaseAggregateException {
+	public constructor(message: string, code?: number) {
+		super(
+			[
+				new TestException('First inner exception'),
+				new TestException('Second inner exception'),
+				new TestException('Third inner exception'),
+			],
+			message,
+			{ code },
+		);
+	}
+}

package/src/tests/test.exception.ts

@@ -0,0 +1,7 @@
+import { BaseException } from '../exceptions/index.js';
+
+export class TestException extends BaseException {
+	public constructor(message: string, code?: number) {
+		super(message, { code });
+	}
+}

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from './stack-trace.formatter.js';

package/src/utils/stack-trace.formatter.ts

@@ -0,0 +1,30 @@
+import os from 'os';
+import { SOURCE_MAP_ENABLED } from '../consts.js';
+
+export class StackTraceFormatter {
+	public static format(stack: string, exceptionName: string): string[] {
+		return StackTraceFormatter.getStackLines(stack, exceptionName);
+	}
+
+	protected static getStackLines(stack: string, exceptionName: string): string[] {
+		let lines = stack.split(os.EOL)
+			.splice(1)
+			.filter(stackLine => !StackTraceFormatter.isInternalStackLine(stackLine))
+			.map(line => line.trim());
+
+		if (SOURCE_MAP_ENABLED) {
+			lines = lines.slice(4);
+		}
+		const lineFromExceptionConstructor = lines.findIndex(line => line.startsWith(`at new ${exceptionName}`));
+
+		if (lineFromExceptionConstructor > -1) {
+			return lines.slice(lineFromExceptionConstructor + 1);
+		}
+
+		return lines;
+	}
+
+	protected static isInternalStackLine(line: string): boolean {
+		return line.includes('internal/') && !line.includes('processTicksAndRejections');
+	}
+}