lifelands

@lifelands/errors (0.1.0)

Published 2026-10-26 09:09:57 +00:00 by esfandiari

Installation

@lifelands:registry=https://git.lifelands.ir/api/packages/lifelands/npm/
npm install @lifelands/errors@0.1.0
"@lifelands/errors": "0.1.0"

About this package

Shared error contract, catalog, normalizer, and framework adapters for LifeLands Node/TypeScript services (Express, NestJS, Fastify, Socket.IO)

@lifelands/errors — قرارداد و پکیج مشترک مدیریت خطا

مخزن رسمی قرارداد خطا (Error Contract) بین تمام سرویس‌های Node/TypeScript لایف‌لندز (Express، NestJS، Fastify، Socket.IO) و کلاینت‌های وب و اندروید.

ویژگی‌های کلیدی

  1. هسته مستقل از فریم‌ورک (@lifelands/errors):
    • AppError (با پشتیبانی از cause، category، code، details، fields، retryable، retryAfterSec و expose).
    • HandledError به‌عنوان زیرکلاس سازگار با عقب (Backward-Compatible) برای مهاجرت تدریجی سرویس Express فعلی.
    • defineErrors(domain, defs) برای تعریف کاتالوگ خطاهای دامنه در هر سرویس و exportCatalogJson برای تولید فایل JSON جهت کدجن وب/اندروید و مستندات OpenAPI.
  2. قرارداد پاسخ واحد سازگار با N/N−1 (ErrorEnvelope):
    • حفظ state: false، message، code و details در سطح اول برای کلاینت‌های قدیمی.
    • حفظ success: false، data: null و شیء استاندارد error برای سرویس‌های جدید (NestJS / Fastify) و کلاینت‌های جدید.
  3. تفکیک خطاهای احراز هویت (AUTH.USER_NOT_FOUND در برابر AUTH.WRONG_PASSWORD):
    • به‌صورت پیش‌فرض (authDisclosurePolicy: 'detailed') بین «کاربر یافت نشد» (action: 'REGISTER') و «کلمه عبور اشتباه است» (action: 'FORGOT_PASSWORD') تمایز قائل می‌شود و در صورت نیاز سرویس‌های خاص، قابلیت سوئیچ به 'generic' (AUTH.INVALID_CREDENTIALS) را بدون تغییر لاگ و متریک داخلی دارد.
  4. یک Normalizer واحد (toAppError):
    • نگاشت متمرکز خطاهای Mongo (E11000، قطعی شبکه، تایم‌اوت، تداخل تراکنش)، Mongoose (ValidationError، CastError)، Postgres (23505، 23503، 40001، خطاهای اتصال)، Joi، NestJS HttpException و class-validator، Fastify validation، خطاهای JWT و خطاهای Axios/HTTP.
  5. جلوگیری از Catch-all و دلیل اشتباه (callExternal و withDb):
    • بسته‌بندی خطاها فقط در مرز I/O با حفظ cause اصلی و نام سرویس/عملیات.
  6. آداپتورهای آماده:
    • @lifelands/errors/express
    • @lifelands/errors/nestjs
    • @lifelands/errors/fastify
    • @lifelands/errors/socket
    • @lifelands/errors/http-client

Dependencies

Development Dependencies

ID Version
@types/node ^22.10.5
tsx ^4.23.15
typescript ^5.6.3

Peer Dependencies

ID Version
@nestjs/common >=9.0.0
axios >=0.27.0
express >=4.17.0
fastify >=4.0.0
mongoose >=6.0.0
Details
npm
2026-10-26 09:09:57 +00:00
308
UNLICENSED
latest
32 KiB
Assets (1)
Versions (1) View all
0.1.0 2026-10-26