@ecash/shared

Shared utilities for Ecash microservices - Message handling, i18n, error helpers.

Features

• i18n Message System: Get localized messages from database with caching
• Parameter Replacement: Dynamic message templates with {placeholder} support
• Language Detection: Auto-detect language from request headers or query params
• Error Helpers: Throw errors with dynamic, localized messages

Installation

npm install @ecash/shared

Setup

1. Prepare Database Messages

Create messages in your messages collection:

{
  "code": "ECASH_00001",
  "classificationCode": "ECASH",
  "content": {
    "vi": "Metadata không hợp lệ theo schema của project type '{projectTypeCode}': {errors}",
    "en": "Metadata is invalid according to project type '{projectTypeCode}' schema: {errors}",
    "ko": "프로젝트 유형 '{projectTypeCode}'의 스키마에 따라 메타데이터가 유효하지 않습니다: {errors}"
  }
}

2. Implement MessageServicePort

Each microservice implements the message service:

// ecash-marketplace/src/application/services/message/get-message-content.service.ts
import { MessageServicePort } from "@ecash/shared";

export class GetMessageContentService implements MessageServicePort {
  async getMessageContentByCode(code: string, language: string) {
    // Your implementation - query DB/Redis
    const cached = await redis.get(`message:${code}:${language}`);
    if (cached) return JSON.parse(cached);

    const message = await db.collection("messages").findOne({ code });
    return {
      code: message.code,
      classificationCode: message.classificationCode,
      message: message.content[language],
    };
  }
}

Usage

1. Get Language from Request

import { getLanguageFromRequest } from "@ecash/shared";

const language = getLanguageFromRequest(request); // "vi", "en", "ko"

2. Get Localized Message

import { getMessage } from "@ecash/shared";

const message = await getMessage(messageService, "ECASH_00001", "vi", {
  projectTypeCode: "APARTMENT",
  errors: "field required",
});
// Returns: "Metadata không hợp lệ theo schema của project type 'APARTMENT': field required"

3. Get Message from Request (Shorthand)

import { getMessageFromRequest } from "@ecash/shared";

const message = await getMessageFromRequest(
  request,
  messageService,
  "ECASH_00001",
  { projectTypeCode: "APARTMENT" },
);

4. Throw Message Error

import { throwMessageError } from "@ecash/shared";

await throwMessageError(
  messageService,
  "vi",
  "ECASH_00001",
  { projectTypeCode: "APARTMENT", errors: "field required" },
  "COMM0400",
);

5. Create Message Error (without throwing)

import { createMessageError } from "@ecash/shared";

const error = await createMessageError(messageService, "vi", {
  messageCode: "ECASH_00001",
  responseCode: "COMM0400",
  params: { projectTypeCode: "APARTMENT" },
});

throw error;

API Reference

getLanguageFromRequest(request, defaultLang?)

Extract language from request headers or query params.

• Priority: Accept-Language header > ?lang= query > defaultLang
• Returns: Language code ("vi", "en", "ko")

getMessage(messageService, code, language, params?)

Get localized message with parameter replacement.

• messageService: Service implementing MessageServicePort
• code: Message code from database
• language: Target language
• params: Object with key-value pairs to replace {key} in template

getMessageFromRequest(request, messageService, code, params?)

Shorthand that extracts language from request and gets message.

throwMessageError(messageService, language, messageCode, params?, responseCode?, statusCode?)

Throw error with localized message from database.

createMessageError(messageService, language, options)

Create MessageError object without throwing.

Language Detection

The library detects language in this order:

1. Header: Accept-Language: vi-VN, vi;q=0.9 → "vi"
2. Query: ?lang=en → "en"
3. Default: "vi"

Message Template Syntax

Use {key} placeholders in your message templates:

{
  "content": {
    "vi": "Xin chào {name}, bạn có {count} tin nhắn mới",
    "en": "Hello {name}, you have {count} new messages"
  }
}

getMessage(messageService, "MSG_00001", "vi", { name: "John", count: 5 });
// "Xin chào John, bạn có 5 tin nhắn mới"

Publishing

cd ecash-shared
npm run build
npm publish

License

PRIVATE - Ecash internal use only.