error

🐞 DWS Error

If you've ever debugged a production incident with nothing but a generic Error("something went wrong"), you know the pain.
This package gives your errors structure, every exception carries a UUID v7, a timestamp, and an optional HTTP status code, so you can always trace what happened and when.

Why this package?

Vanilla Error objects lack context.
You end up manually adding IDs, timestamps, and status codes everywhere, or worse, you don't, and debugging becomes a guessing game.

@dws-std/error solves that with two classes:

• Exception - a richer base error with automatic UUID v7 tracking, timestamps, and an optional error code.
• HttpException - extends Exception with an HTTP status code, perfect for API error responses.

No dependencies, no bloat. Just structured errors that make your life easier.

📌 Table of Contents

• Features
• Installation
• Usage
• API Reference
• License
• Contact

✨ Features

• 🔍 UUID v7 Tracking : Every exception gets a unique, time-sortable ID out of the box.
• 📅 Built-in Context : Timestamp, error code, and cause are baked into each instance.
• 🌐 HTTP-Aware : HttpException maps to any standard HTTP status for clean API responses.
• 📦 Zero Dependencies : Pure TypeScript, tiny footprint.

🔧 Installation

bun add @dws-std/error

⚙️ Usage

Exception - General-Purpose Errors

Use Exception whenever you need a traceable error with more context than a plain Error.

import { Exception } from '@dws-std/error';

throw new Exception('Configuration file not found', {
	code: 'CONFIG_NOT_FOUND'
});

Every instance automatically carries a uuid and a date, so you can correlate it in your logs without any extra work.

You can also wrap a root cause to preserve the original error:

import { Exception } from '@dws-std/error';

try {
	await db.save(user);
} catch (err) {
	throw new Exception('Failed to persist user', { cause: err });
}

HttpException - API Errors

When you're building an API and need an error tied to an HTTP status code, reach for HttpException.
Pass a status key like 'BAD_REQUEST' or a numeric code like 400, both work.

import { HttpException } from '@dws-std/error';

throw new HttpException('Invalid email address', {
	status: 'BAD_REQUEST',
	code: 'INVALID_EMAIL'
});

If you don't specify a status, it defaults to 500 Internal Server Error, so unexpected failures are covered too:

import { HttpException } from '@dws-std/error';

throw new HttpException('Something broke');

📚 API Reference

Full docs: Dominus-Web-Service.github.io/packages

⚖️ License

MIT - Feel free to use it.

📧 Contact

• GitHub: Dominus-Web-Service