Skip to content

Latest commit

 

History

History
276 lines (185 loc) · 7.24 KB

Exception.md

File metadata and controls

276 lines (185 loc) · 7.24 KB

Exception

Enhanced error handling with expressive error reporting and stack trace support. Provides better error information than standard JavaScript errors with template-based error messages, validation error aggregation, enhanced stack trace parsing, and HTTP status code integration.

const exception = new Exception('Invalid Parameters: %s', 400)
  .withErrors({
    name: 'required',
    email: 'invalid format'
  })
  .withPosition(100, 200);

1. Static Methods

The following methods can be accessed directly from Exception itself. These factory methods provide convenient ways to create Exception instances for common error scenarios without needing to instantiate the class directly.

1.1. Creating Exceptions with Templates

The following example shows how to create exceptions with template strings using placeholder substitution.

throw Exception.for('Something %s is %s', 'good', 'bad');
// Results in: "Something good is bad"

Parameters

Parameter Type Description
message string Template message with %s placeholders
...values unknown[] Values to replace %s placeholders

Returns

A new Exception instance with the formatted message.

1.2. Creating Exceptions from Response Objects

The following example shows how to create exceptions from response objects containing error details.

const response = { 
  code: 400, 
  error: 'Bad Request', 
  errors: { field: 'required' } 
};
throw Exception.forResponse(response);

Parameters

Parameter Type Description
response Partial<StatusResponse> Response object with error details
message string Fallback message if response.error is not provided

Returns

A new Exception instance configured from the response object.

1.3. Creating Exceptions for Validation Errors

The following example shows how to create exceptions specifically for validation errors with field-specific error messages.

throw Exception.forErrors({
  name: 'required',
  email: 'invalid format'
});

Parameters

Parameter Type Description
errors NestedObject<string> Object containing validation errors

Returns

A new Exception instance with "Invalid Parameters" message and error details.

1.4. Requiring Conditions

The following example shows how to assert conditions and throw exceptions if they fail.

Exception.require(count > 0, 'Count %s must be positive', count);

Parameters

Parameter Type Description
condition boolean Condition that must be true
message string Error message with %s placeholders
...values any[] Values to replace %s placeholders

Returns

Void if condition is true, throws Exception if false.

1.5. Try-Catch Wrapper

The following example shows how to use the synchronous try-catch wrapper for safe operation execution.

const result = Exception
  .try(() => riskyOperation())
  .catch((error, kind) => {
    console.log('Error type:', kind);
    return defaultValue;
  });

Parameters

Parameter Type Description
callback () => T Function to execute safely

Returns

An object with a catch method for handling errors.

1.6. Upgrading Errors

The following example shows how to upgrade regular errors to exceptions with additional context.

try {
  // some operation
} catch (error) {
  throw Exception.upgrade(error, 400);
}

Parameters

Parameter Type Description
error Error The error to upgrade
code number HTTP status code (default: 500)

Returns

An Exception instance (returns original if already an Exception).

2. Properties

The following properties are available when instantiating an Exception. These properties provide access to error details, HTTP status codes, and position information for debugging purposes.

Property Type Description
code number HTTP status code
end number Ending character position of the error
errors object Validation errors object
start number Starting character position of the error
type string Exception type name

3. Methods

The following methods are available when instantiating an Exception. These methods allow you to configure the exception with additional context and convert it to various formats for different use cases.

3.1. Setting Error Code

The following example shows how to set the HTTP status code for the exception.

exception.withCode(404);

Parameters

Parameter Type Description
code number HTTP status code

Returns

The Exception instance to allow method chaining.

3.2. Adding Validation Errors

The following example shows how to add validation errors with field-specific error messages.

exception.withErrors({
  name: 'required',
  email: ['required', 'invalid format']
});

Parameters

Parameter Type Description
errors NestedObject<string|string[]> Validation errors object

Returns

The Exception instance to allow method chaining.

3.3. Setting Position Information

The following example shows how to set character position information for parsing errors.

exception.withPosition(100, 200);

Parameters

Parameter Type Description
start number Starting character position
end number Ending character position

Returns

The Exception instance to allow method chaining.

3.4. Converting to Response Object

The following example shows how to convert the exception to a response object suitable for API responses.

const response = exception.toResponse();
// Returns: { code, status, error, start, end, stack, errors? }

Parameters

Parameter Type Description
start number Starting index for stack trace (default: 0)
end number Ending index for stack trace (default: 0)

Returns

An ErrorResponse object with all exception details.

3.5. Converting to JSON

The following example shows how to convert the exception to a formatted JSON string.

const json = exception.toJSON();
console.log(json); // Pretty-printed JSON string

Returns

A formatted JSON string representation of the exception.

3.6. Getting Stack Trace

The following example shows how to get the parsed stack trace with detailed frame information.

const trace = exception.trace();
trace.forEach(frame => {
  console.log(`${frame.method} at ${frame.file}:${frame.line}:${frame.char}`);
});

Parameters

Parameter Type Description
start number Starting index for stack trace (default: 0)
end number Ending index for stack trace (default: 0)

Returns

An array of Trace objects with method, file, line, and char information.