@jnpt/nest-logging 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,775 @@
-# Temporary Holding Version
+# NestJS Structured Logs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Library สำหรับทำ **structured JSON logging** ใน NestJS (ทั้ง **Express** และ **Fastify**) — port มาจาก Go library
+[`github.com/jnpt-golangs/logging`](../go_logging) โดยมี feature และรูปแบบ log JSON เหมือนกันทุกอย่าง
+มี log 2 ประเภทหลักคือ **`application`** และ **`request`**
+
+## Features
+
+- 📝 **Structured JSON Logging** — ทุก log ออกเป็น JSON 1 บรรทัด ไปที่ `stdout` (field เหมือน Go version ทุกตัว)
+- 🔗 **Correlation ID** — รับ/สร้าง `X-Correlation-ID` อัตโนมัติ และส่งต่อไปทุก log ใน request เดียวกันโดยไม่ต้องส่ง context เอง
+- 📥 **Incoming Request Logging** — log request + response ของทุก route เป็น entry เดียว (Express middleware / Fastify hooks — เลือกให้อัตโนมัติ)
+- 📤 **Outgoing Request Logging** — log การเรียก service ภายนอกผ่าน `fetch` พร้อมส่ง correlation ID ต่อ
+- 🔒 **Security** — mask header และ field ที่เป็นความลับอัตโนมัติ (case-insensitive, nested object/array)
+- ⚙️ **Configurable** — config ได้ทุกอย่างเหมือน Go version และทุกค่าเป็น optional
+- ⚡ **Express และ Fastify 100%** — `@nestjs/platform-express` และ `@nestjs/platform-fastify` ได้ข้อมูลใน log ครบเท่ากัน รวมถึง Express / Fastify แบบไม่ใช้ Nest
+- ✅ ทดสอบแล้วกับ NestJS 10, 11, 12 (CommonJS และ ESM), Express 4/5, Fastify 4/5, Node.js >= 18
+
+---
+
+## สารบัญ
+
+1. [Installation](#installation)
+2. [Quick Start (3 ขั้นตอน)](#quick-start-3-ขั้นตอน)
+3. [Application Logging](#application-logging)
+4. [Incoming Request Logging (Middleware)](#incoming-request-logging-middleware)
+5. [Fastify](#fastify)
+6. [Outgoing Request Logging (HTTP Client)](#outgoing-request-logging-http-client)
+7. [Correlation ID](#correlation-id)
+8. [Masking](#masking)
+9. [Configuration](#configuration)
+10. [รูปแบบ Log JSON](#รูปแบบ-log-json)
+11. [API Reference](#api-reference)
+12. [เทียบกับ Go version](#เทียบกับ-go-version)
+13. [Development](#development)
+
+---
+
+## Installation
+
+### 1. ติดตั้ง package
+
+package นี้ชื่อ `@jnpt/nest-logging` (แก้ชื่อได้ที่ `package.json`) เลือกวิธีใดวิธีหนึ่ง:
+
+```bash
+# ก) ติดตั้งจาก registry (หลัง publish ด้วย `npm publish --access public`)
+npm install @jnpt/nest-logging
+
+# ข) ติดตั้งจาก git repository
+npm install git+ssh://git@github.com/jnpt-nestjs-templates/logging.git
+# หรือ (ระบุ tag/branch ได้): npm install github:jnpt-nestjs-templates/logging#main
+
+# ค) ติดตั้งจากโฟลเดอร์ในเครื่อง (ระหว่างพัฒนา)
+npm install /Volumes/JP/Projects/Loggings/nest_logging
+
+# ง) ติดตั้งจากไฟล์ tarball
+cd /Volumes/JP/Projects/Loggings/nest_logging && npm pack   # ได้ไฟล์ jnpt-nest-logging-1.0.0.tgz
+cd /path/to/your-nest-app && npm install /path/to/jnpt-nest-logging-1.0.0.tgz
+```
+
+> วิธี ข/ค/ง จะ build ให้อัตโนมัติผ่าน script `prepare` (`tsc` → `dist/`)
+
+### 2. Requirements
+
+| สิ่งที่ต้องมี | เวอร์ชัน |
+|---|---|
+| Node.js | >= 18 (ใช้ `fetch`, `AsyncLocalStorage`, `crypto.randomUUID` ของ Node) |
+| `@nestjs/common` | >= 9 (peer dependency — มีอยู่แล้วในโปรเจกต์ Nest) |
+| HTTP platform | `@nestjs/platform-express` (default ของ Nest) **หรือ** `@nestjs/platform-fastify` |
+
+ไม่มี runtime dependency อื่นเลย
+
+---
+
+## Quick Start (3 ขั้นตอน)
+
+### ขั้นที่ 1 — import `LoggingModule` ใน `AppModule`
+
+```ts
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { LoggingModule } from '@jnpt/nest-logging';
+
+@Module({
+  imports: [
+    LoggingModule.forRoot({ applicationName: 'my-service' }), // config ทุกตัว optional
+  ],
+  controllers: [UsersController],
+  providers: [UsersService],
+})
+export class AppModule {}
+```
+
+แค่นี้ทุก request ที่เข้ามาจะถูก log อัตโนมัติ (ยกเว้น `/health`, `/metrics`, `/favicon.ico`)
+
+### ขั้นที่ 2 — ใช้ `AppLogger` ใน service / controller
+
+```ts
+// users.service.ts
+import { Injectable } from '@nestjs/common';
+import { AppLogger } from '@jnpt/nest-logging';
+
+@Injectable()
+export class UsersService {
+  private readonly log = new AppLogger(UsersService.name);
+
+  findOne(id: string) {
+    this.log.info('Fetching user', { user_id: id }); // correlation_id ใส่ให้อัตโนมัติ
+    // ...
+  }
+}
+```
+
+### ขั้นที่ 3 (แนะนำ) — เปิด `rawBody` ใน `main.ts`
+
+```ts
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import { AppLogger } from '@jnpt/nest-logging';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const log = new AppLogger('main');
+  const app = await NestFactory.create(AppModule, { rawBody: true }); // ให้ log request body แบบ raw เหมือน Go
+  await app.listen(8080);
+  log.info('Starting server on :8080');
+}
+bootstrap();
+```
+
+> `rawBody: true` ไม่บังคับ — ถ้าไม่เปิด middleware จะใช้ `req.body` ที่ Nest parse แล้วแทน (ดู [รายละเอียด](#request-body-ถูกเก็บอย่างไร))
+
+---
+
+## Application Logging
+
+สร้าง logger ด้วยชื่อ (ไปอยู่ใน field `logger_name`):
+
+```ts
+import { AppLogger } from '@jnpt/nest-logging';
+
+const log = new AppLogger('MyService');            // ใช้ global default config (จาก LoggingModule.forRoot / configureDefaults)
+const custom = new AppLogger('Other', {            // ใช้ config ของตัวเอง (partial ได้ ที่เหลือใช้ค่า default)
+  applicationName: 'other-app',
+  minLevel: 'WARN',
+});
+```
+
+### Methods
+
+| Method | Level | หมายเหตุ |
+|---|---|---|
+| `debug(message, ...extra)` | DEBUG | |
+| `info(message, ...extra)` | INFO | |
+| `warn(message, ...extra)` | WARN | |
+| `warnError(message, err, ...extra)` | WARN | แนบ `error` (class, message, stack_trace) |
+| `error(message, ...extra)` | ERROR | |
+| `errorWithErr(message, err, ...extra)` | ERROR | แนบ `error` (class, message, stack_trace) |
+| `logIncomingHttp(...)` | ตาม status | middleware เรียกให้ ปกติไม่ต้องเรียกเอง |
+| `logOutgoingHttp(...)` | ตาม status | `createLoggingFetch` เรียกให้ ปกติไม่ต้องเรียกเอง |
+| `setOutput(writer)` | — | เปลี่ยนปลายทาง log (default `process.stdout`) |
+
+### ตัวอย่าง
+
+```ts
+log.info('Processing started');
+log.debug('Debug information');
+log.warn('Warning message');
+
+// extra เป็น object ธรรมดา
+log.info('User action', { userId: '12345', action: 'LOGIN' });
+
+// extra เป็น class instance / DTO ก็ได้ (แปลงผ่าน JSON)
+class OrderDto { constructor(public orderId: string, public amount: number) {} }
+log.info('Order created', new OrderDto('A-1', 100));
+
+// ส่ง extra หลายตัว → merge เป็น object เดียว (key ซ้ำตัวหลังชนะ)
+log.info('Merged', { a: 1 }, { b: 2 });             // extra: { a: 1, b: 2 }
+
+// extra ที่ไม่ใช่ object (array, string, number) → เก็บใน key "data"
+log.info('List', [1, 2, 3]);                        // extra: { data: [1, 2, 3] }
+
+// log พร้อม error
+try {
+  await doSomething();
+} catch (err) {
+  log.errorWithErr('Error occurred', err, { step: 'doSomething' });
+}
+log.warnError('Invalid request body', new Error('email is required'));
+```
+
+### Log level
+
+ลำดับ: `TRACE`(5000) < `DEBUG`(10000) < `INFO`(20000) < `WARN`(30000) < `ERROR`(40000)
+
+`minLevel` (default `DEBUG`) — log ที่ level ต่ำกว่านี้จะไม่ถูกเขียน ถ้าใส่ค่าไม่ถูกต้องจะถือเป็น `DEBUG`
+
+### Error / Stack trace
+
+- `error.class` = ชื่อ class ของ error เช่น `Error`, `TypeError`, `HttpException` (ถ้าไม่ใช่ `Error` จะเป็น `typeof` เช่น `string`)
+- `error.stack_trace` = array ของ frame จาก `err.stack` จำกัดที่ `applicationLogging.maxStackTraceDepth` (default 50)
+- เหมือน Go: ส่วน `error` จะถูกใส่ **เฉพาะเมื่อ** `applicationLogging.includeStackTrace = true` (default)
+- V8 เก็บ stack แค่ 10 frame เป็นค่า default — ถ้าต้องการมากกว่านั้นให้ตั้ง `Error.stackTraceLimit = 50` ใน `main.ts`
+
+### เปลี่ยนปลายทาง output
+
+```ts
+import { createWriteStream } from 'node:fs';
+log.setOutput(createWriteStream('app.log', { flags: 'a' }));   // อะไรก็ได้ที่มี write(string)
+log.setOutput({ write: (line) => myCollector.push(line) });     // เช่นใน unit test
+```
+
+---
+
+## Incoming Request Logging (Middleware)
+
+### แบบที่ 1 — ง่ายสุด (แนะนำ): `LoggingModule.forRoot()`
+
+```ts
+@Module({
+  imports: [LoggingModule.forRoot()],                       // ใช้ default config ทั้งหมด
+})
+export class AppModule {}
+```
+
+```ts
+@Module({
+  imports: [
+    LoggingModule.forRoot({                                 // หรือกำหนด config เอง (เฉพาะที่ต้องการ)
+      applicationName: 'my-service',
+      requestLogging: {
+        logBody: true,
+        logResponseBody: true,
+        maxBodySize: 10000,
+        excludePatterns: ['/health', '/metrics'],
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`forRoot(config)` ทำ 2 อย่าง: (1) เรียก `configureDefaults(config)` ตั้ง global default config
+และ (2) apply `LoggingMiddleware` กับทุก route (`forRoutes('*')`) — logger ของ middleware ชื่อ `LoggingMiddleware`
+
+### แบบที่ 2 — กำหนดเองว่าจะใช้กับ route ไหน: `LoggingMiddleware`
+
+```ts
+import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
+import { configureDefaults, LoggingMiddleware } from '@jnpt/nest-logging';
+
+configureDefaults({ applicationName: 'my-service' });
+
+@Module({ /* ... */ })
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(LoggingMiddleware).forRoutes(UsersController, OrdersController);
+  }
+}
+```
+
+### แบบที่ 3 — ใช้ logger / config เฉพาะตัว: `createLoggingMiddleware(logger, config?)`
+
+เทียบเท่า `middleware.LoggingMiddleware(log, config)` ของ Go ใช้กับ `app.use()` ได้เลย:
+
+```ts
+// main.ts
+import { AppLogger, createLoggingMiddleware } from '@jnpt/nest-logging';
+
+const app = await NestFactory.create(AppModule, { rawBody: true });
+const log = new AppLogger('main');
+app.use(createLoggingMiddleware(log));                                    // ใช้ default config
+// หรือ
+app.use(createLoggingMiddleware(log, { requestLogging: { maxBodySize: 2048 } })); // config ของตัวเอง
+```
+
+> **หมายเหตุ (เหมือน Go):** `config` ของ middleware ควบคุมแค่ exclude/include patterns, การเก็บ body และ `maxBodySize`
+> ส่วน `application`, masking, `logHeaders` และการเปิด/ปิด log มาจาก config ของ **logger** ที่ส่งเข้าไป —
+> ถ้าต้องการให้ตรงกันให้สร้าง logger ด้วย config เดียวกัน: `new AppLogger('main', cfg)` + `createLoggingMiddleware(log, cfg)`
+>
+> แบบที่ 3 ห้ามใช้ร่วมกับ `LoggingModule.forRoot()` ไม่งั้นจะได้ log ซ้ำ 2 รอบ — ถ้าจะตั้ง global config ให้ใช้ `configureDefaults()` แทน
+> และควร `app.use(...)` ก่อน `app.listen()`
+
+### Middleware ทำอะไรบ้าง (ตามลำดับ — เหมือนกันทั้ง Express และ Fastify)
+
+1. ถ้า path ตรง `excludePatterns` (หรือไม่ตรง `includePatterns` เมื่อกำหนดไว้) → ข้าม ไม่ log และไม่ใส่ correlation ID
+2. อ่าน header `X-Correlation-ID` ถ้าไม่มีจะสร้าง UUID ใหม่ → ใส่ใน response header `X-Correlation-ID` และใน async context
+3. ดักเก็บ response body (`res.write` / `res.end`)
+4. เมื่อ response ส่งเสร็จ (รวมถึงกรณี exception, 404, client ตัดการเชื่อมต่อ) → เขียน log `"Incoming request"` 1 entry ที่มี:
+   method, uri (path ไม่รวม query), status_code, duration_ms, remote_address, user_agent,
+   request headers / query_params / path_params / body / content_type / content_length,
+   response headers / body / content_type / content_length
+5. level ตาม status: `< 400` → INFO, `400–499` → WARN, `>= 500` → ERROR
+
+### Request body ถูกเก็บอย่างไร
+
+| กรณี | สิ่งที่ log |
+|---|---|
+| เปิด `rawBody: true` | raw bytes → ถ้า parse JSON ได้ใช้ JSON, ไม่ได้ใช้ข้อความดิบตัดที่ `maxBodySize` bytes + `... [TRUNCATED]` (เหมือน Go ทุกประการ) |
+| ไม่เปิด `rawBody` | `req.body` ที่ Nest parse แล้ว (JSON / urlencoded → object), ถ้าเป็น string/Buffer ใช้กฎเดียวกับด้านบน |
+| ไม่มี body | ไม่มี key `body` |
+
+response body ใช้กฎเดียวกัน: JSON → object, อย่างอื่น → ข้อความตัดที่ `maxBodySize`
+(เหมือน Go: JSON ไม่ถูกตัด, ตัดเฉพาะข้อความที่ไม่ใช่ JSON) — ถ้า `logResponseBody: false` จะไม่เก็บ body ไว้ในหน่วยความจำเลย
+
+---
+
+## Fastify
+
+ทำงานได้ครบ 100% เท่ากับ Express ทั้งแบบ NestJS + `FastifyAdapter` และแบบ Fastify ล้วน
+(ข้อมูลใน log เหมือนกันทุก field: path_params, query_params, request/response body, masking, correlation ID, level ตาม status)
+
+ใน Fastify library จะใช้ **Fastify hooks** (`onRequest` + `preHandler`) แทน middleware
+เพราะ middleware ของ Nest บน Fastify (ผ่าน middie) จะไม่เห็น `request.params` และ `request.body`
+
+### NestJS + Fastify (ตาม [NestJS Performance (Fastify)](https://docs.nestjs.com/techniques/performance))
+
+```bash
+npm install @nestjs/platform-fastify
+```
+
+```ts
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
+import { AppLogger } from '@jnpt/nest-logging';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const log = new AppLogger('main');
+  const app = await NestFactory.create<NestFastifyApplication>(
+    AppModule,
+    new FastifyAdapter(),
+    { rawBody: true },                // optional: log raw request body เหมือน Go
+  );
+  await app.listen(8080, '0.0.0.0');
+  log.info('Starting server on :8080');
+}
+bootstrap();
+```
+
+`AppModule` **ไม่ต้องแก้อะไรเลย** — ใช้ `LoggingModule.forRoot()` ตัวเดิม
+มันจะตรวจ HTTP adapter เอง: เป็น Express ก็ใช้ `LoggingMiddleware`, เป็น Fastify ก็ลง hooks ให้อัตโนมัติ
+`AppLogger`, `createLoggingFetch` และ correlation ID ใช้เหมือนเดิมทุกอย่าง
+
+> บน Fastify อย่าใช้ `consumer.apply(LoggingMiddleware)` เอง (ได้ log ไม่ครบเพราะเหตุผลด้านบน) — ให้ใช้ `LoggingModule.forRoot()`
+> หรือถ้าต้องการ logger/config เฉพาะตัวให้ใช้ `createFastifyLoggingPlugin` แบบด้านล่าง:
+>
+> ```ts
+> const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter());
+> await app.register(createFastifyLoggingPlugin(new AppLogger('main'), { requestLogging: { maxBodySize: 2048 } }));
+> ```
+> (กรณีนี้ไม่ต้อง import `LoggingModule` — ใช้ `configureDefaults()` ตั้ง global config แทน ไม่งั้นจะได้ log ซ้ำ)
+
+### Fastify ล้วน (ไม่ใช้ NestJS)
+
+```ts
+import Fastify from 'fastify';
+import { AppLogger, configureDefaults, createFastifyLoggingPlugin, createLoggingFetch } from '@jnpt/nest-logging';
+
+configureDefaults({ applicationName: 'my-service' });
+const log = new AppLogger('main');
+
+const app = Fastify();
+await app.register(createFastifyLoggingPlugin(log));      // หรือ createFastifyLoggingPlugin(log, config)
+
+app.get('/api/users/:id', async (req) => {
+  new AppLogger('UserHandler').info('Fetching user');     // มี correlation_id อัตโนมัติ
+  return { id: (req.params as { id: string }).id };
+});
+
+await app.listen({ port: 8080, host: '0.0.0.0' });
+```
+
+- plugin นี้ **ไม่ encapsulated** (เทียบเท่าห่อด้วย `fastify-plugin`) จึงครอบทุก route รวมถึง route ใน child plugin/prefix
+- จะใช้ `registerFastifyLogging(app, log, config?)` (เรียก `addHook` ตรงๆ) แทน `register` ก็ได้ ผลเหมือนกัน
+- เก็บ response body ได้ทั้ง payload ปกติและแบบ stream
+- ไม่ต้องลง `fastify-plugin` หรือ `@fastify/middie` เพิ่ม
+
+### Express ล้วน (ไม่ใช้ NestJS)
+
+```ts
+import express from 'express';
+import { AppLogger, createLoggingMiddleware } from '@jnpt/nest-logging';
+
+const app = express();
+app.use(express.json());
+app.use(createLoggingMiddleware(new AppLogger('main')));
+```
+
+---
+
+## Outgoing Request Logging (HTTP Client)
+
+`createLoggingFetch(logger, config?, baseFetch?)` คืนค่า function ที่ใช้แทน `fetch` ได้ทันที (เทียบเท่า `httpclient.NewClient` ของ Go)
+
+### แบบง่าย (ใช้ default config)
+
+```ts
+import { AppLogger, createLoggingFetch } from '@jnpt/nest-logging';
+
+const log = new AppLogger('MyService');
+const fetch = createLoggingFetch(log);
+```
+
+### แบบกำหนด config เอง
+
+```ts
+const fetch = createLoggingFetch(log, {
+  applicationName: 'my-service',
+  requestLogging: { logBody: true, logResponseBody: true },
+});
+```
+
+### ใช้ใน NestJS service
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { AppLogger, createLoggingFetch } from '@jnpt/nest-logging';
+
+@Injectable()
+export class TodoClient {
+  private readonly log = new AppLogger(TodoClient.name);
+  private readonly fetch = createLoggingFetch(this.log);
+
+  async getTodo(id: number) {
+    const res = await this.fetch(`https://jsonplaceholder.typicode.com/todos/${id}`);
+    return res.json(); // อ่าน body ได้ตามปกติ (logger อ่านจาก clone)
+  }
+
+  async createTodo(todo: unknown) {
+    const res = await this.fetch('https://jsonplaceholder.typicode.com/todos', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(todo),
+    });
+    return res.json();
+  }
+}
+```
+
+### ทำอะไรบ้าง
+
+1. ใช้ correlation ID ของ request ปัจจุบัน (ถ้าไม่มี เช่นเรียกจาก cron job จะสร้างใหม่) แล้วใส่ header `X-Correlation-ID`
+2. เก็บ request body (string, `URLSearchParams`, `Buffer`/`Uint8Array`, `ArrayBuffer`, `Blob`, หรือ `Request` object) — stream/FormData จะส่งปกติแต่ไม่ log body
+3. เรียก `fetch` จริง แล้ว log `"Outgoing request"` 1 entry พร้อม `extra: { "direction": "outgoing" }`, level ตาม status
+4. ถ้า network error → log ERROR `"Outgoing request failed"` พร้อม `extra: { method, url, duration_ms }` และ error แล้ว **throw ต่อ**
+
+ใช้กับ fetch implementation อื่นได้ผ่าน parameter ที่ 3 เช่น `createLoggingFetch(log, undefined, undiciFetch)`
+
+---
+
+## Correlation ID
+
+Go ต้องส่ง `context.Context` ทุก method — ใน Node ใช้ `AsyncLocalStorage` แทน
+correlation ID จึง "ตามไปเอง" ตลอด async chain ของ request (controller → service → repository → fetch) โดยไม่ต้องส่ง parameter
+
+```ts
+import {
+  CorrelationIDHeader,      // 'X-Correlation-ID'
+  getCorrelationId,         // ดึง correlation ID ปัจจุบัน ('' ถ้าไม่มี)
+  withCorrelationId,        // รัน function ภายใต้ correlation ID ที่กำหนด
+  generateCorrelationId,    // สร้าง UUID v4 ใหม่
+  ensureCorrelationId,      // ID ปัจจุบัน หรือสร้างใหม่ถ้าไม่มี
+} from '@jnpt/nest-logging';
+
+// ใน controller/service (หลัง middleware)
+const id = getCorrelationId();
+
+// งานที่ไม่ได้มาจาก HTTP request เช่น cron, queue consumer, Kafka message
+await withCorrelationId(message.headers['x-correlation-id'] ?? generateCorrelationId(), async () => {
+  log.info('Processing message');      // มี correlation_id
+  await fetch('https://other-service/api');     // ส่ง X-Correlation-ID ต่อ (ถ้าใช้ createLoggingFetch)
+});
+```
+
+---
+
+## Masking
+
+ค่าที่ถูก mask จะถูกแทนด้วย `maskValue` (default `***MASKED***`)
+
+- **Headers** (`maskedHeaders`) default: `Authorization`, `X-Api-Key`, `Cookie`, `Set-Cookie` — ใช้กับทั้ง request และ response
+- **Body fields** (`maskedFields`) default: `password`, `secret`, `token`, `creditCard`, `ssn` — ไล่ทุกชั้นของ object/array ซ้อนกัน
+- เทียบชื่อแบบ **case-insensitive** (`Password`, `PASSWORD`, `password` ถูก mask หมด)
+- เป็นการเทียบชื่อ key ตรงตัว (ไม่ใช่ substring) — `accessToken` จะไม่ถูก mask ถ้าไม่ได้ใส่ไว้
+- body ที่เป็นข้อความดิบ (ไม่ใช่ JSON) จะไม่ถูก mask (เหมือน Go)
+- **Query string** ก็ถูก mask ด้วยรายชื่อเดียวกับ `maskedFields` ทั้ง `query_params` ของ incoming request และ `uri` ของ outgoing request (เช่น `?token=abc` → `?token=***MASKED***`) — ส่วนนี้ **เพิ่มจาก Go version** เพื่อไม่ให้ token/API key ใน URL หลุดไปใน log
+
+การ **เพิ่ม** field (config เป็นการแทนที่ array ไม่ใช่ต่อท้าย):
+
+```ts
+import { defaultConfig, LoggingModule } from '@jnpt/nest-logging';
+
+LoggingModule.forRoot({
+  maskedHeaders: [...defaultConfig().maskedHeaders, 'X-Client-Secret'],
+  maskedFields: [...defaultConfig().maskedFields, 'pin', 'accessToken', 'refreshToken'],
+  maskValue: '[REDACTED]',
+});
+```
+
+ใช้ `MaskingUtil` ตรงๆ ก็ได้:
+
+```ts
+import { buildConfig, MaskingUtil } from '@jnpt/nest-logging';
+const masking = new MaskingUtil(buildConfig());
+masking.maskBody({ user: 'a', password: 'b' });   // { user: 'a', password: '***MASKED***' }
+masking.maskHeaders({ Authorization: 'Bearer x' }); // { Authorization: '***MASKED***' }
+masking.maskUrl('https://api.example.com/x?token=abc&page=1'); // 'https://api.example.com/x?token=***MASKED***&page=1'
+```
+
+---
+
+## Configuration
+
+config **ทุกตัวเป็น optional** — ส่งเฉพาะค่าที่ต้องการเปลี่ยน ที่เหลือใช้ค่า default
+(object ซ้อนจะ merge ทีละ field, array จะ **แทนที่** ทั้ง array)
+
+```ts
+import { ConfigInput } from '@jnpt/nest-logging';
+
+const config: ConfigInput = {
+  applicationName: 'my-service',  // field "application"
+  enabled: true,                  // ปิดทั้งหมด = false
+  minLevel: 'INFO',               // TRACE | DEBUG | INFO | WARN | ERROR (ใช้กับ application log)
+  requestLogging: {
+    enabled: true,                // ปิด log ประเภท request (incoming + outgoing)
+    logHeaders: true,
+    logBody: true,                // request body
+    logResponseBody: true,
+    maxBodySize: 10240,           // bytes, ใช้ตัดข้อความที่ไม่ใช่ JSON
+    excludePatterns: ['/health', '/metrics', '/favicon.ico'],
+    includePatterns: [],          // ถ้ากำหนด จะ log เฉพาะ path ที่ตรง
+  },
+  applicationLogging: {
+    enabled: true,                // ปิด log ประเภท application
+    includeStackTrace: true,
+    maxStackTraceDepth: 50,
+  },
+  maskedHeaders: ['Authorization', 'X-Api-Key', 'Cookie', 'Set-Cookie'],
+  maskedFields: ['password', 'secret', 'token', 'creditCard', 'ssn'],
+  maskValue: '***MASKED***',
+};
+```
+
+### Default Values
+
+| Property | Default |
+|---|---|
+| `applicationName` | `"application"` |
+| `enabled` | `true` |
+| `minLevel` | `"DEBUG"` |
+| `requestLogging.enabled` | `true` |
+| `requestLogging.logHeaders` | `true` |
+| `requestLogging.logBody` | `true` |
+| `requestLogging.logResponseBody` | `true` |
+| `requestLogging.maxBodySize` | `10240` |
+| `requestLogging.excludePatterns` | `["/health", "/metrics", "/favicon.ico"]` |
+| `requestLogging.includePatterns` | `[]` |
+| `applicationLogging.enabled` | `true` |
+| `applicationLogging.includeStackTrace` | `true` |
+| `applicationLogging.maxStackTraceDepth` | `50` |
+| `maskedHeaders` | `["Authorization", "X-Api-Key", "Cookie", "Set-Cookie"]` |
+| `maskedFields` | `["password", "secret", "token", "creditCard", "ssn"]` |
+| `maskValue` | `"***MASKED***"` |
+
+### Path patterns (`excludePatterns` / `includePatterns`)
+
+| Pattern | ตรงกับ |
+|---|---|
+| `/health` | ตรงตัวเท่านั้น (`/health`) |
+| `/api/*` | ทุก path ที่ขึ้นต้นด้วย `/api` (prefix) |
+| `/api/**` | ทุก path ที่ขึ้นต้นด้วย `/api` (prefix) |
+
+ไม่รองรับ glob/regex แบบเต็ม (เหมือน Go) — ตรวจ `excludePatterns` ก่อนเสมอ แล้วจึงตรวจ `includePatterns`
+path ที่ใช้เทียบคือ path เต็ม (รวม global prefix เช่น `/v1/health` ถ้าใช้ `app.setGlobalPrefix('v1')`)
+
+### ตั้ง config จาก environment variable
+
+```ts
+// app.module.ts
+LoggingModule.forRoot({
+  applicationName: process.env.APP_NAME ?? 'my-service',
+  minLevel: process.env.LOG_LEVEL ?? 'INFO',
+  requestLogging: { logResponseBody: process.env.NODE_ENV !== 'production' },
+});
+```
+
+### ตั้ง config ตอนรันไทม์
+
+```ts
+import { configureDefaults, getDefaultConfig } from '@jnpt/nest-logging';
+
+configureDefaults({ minLevel: 'WARN' });  // logger ทุกตัวที่สร้างด้วย new AppLogger(name) จะใช้ค่าใหม่ทันที
+getDefaultConfig().minLevel;              // 'WARN'
+```
+
+---
+
+## รูปแบบ Log JSON
+
+### Application log
+
+```json
+{
+  "@timestamp": "2026-10-25T15:42:45.614+07:00",
+  "@version": "1",
+  "application": "demo-service",
+  "message": "Creating user",
+  "logger_name": "UserHandler",
+  "thread_name": "main",
+  "level": "INFO",
+  "level_value": 20000,
+  "type": "application",
+  "correlation_id": "9b0f069a-d73d-4a1e-a131-cedbb2ae320f",
+  "method": "",
+  "uri": "",
+  "request_body": {},
+  "response_body": {},
+  "extra": { "email": "a@b.c" }
+}
+```
+
+### Request log (incoming)
+
+```json
+{
+  "@timestamp": "2026-10-25T15:42:45.614+07:00",
+  "@version": "1",
+  "application": "demo-service",
+  "message": "Incoming request",
+  "logger_name": "LoggingMiddleware",
+  "thread_name": "main",
+  "level": "INFO",
+  "level_value": 20000,
+  "type": "request",
+  "correlation_id": "9b0f069a-d73d-4a1e-a131-cedbb2ae320f",
+  "method": "POST",
+  "uri": "/api/users",
+  "status_code": 201,
+  "duration_ms": 3,
+  "remote_address": "::1",
+  "user_agent": "curl/8.7.1",
+  "request_body": {
+    "headers": { "Host": "localhost:8080", "Content-Type": "application/json", "Authorization": "***MASKED***" },
+    "query_params": { "a": "1, 2" },
+    "body": { "email": "a@b.c", "password": "***MASKED***" },
+    "content_type": "application/json",
+    "content_length": 40
+  },
+  "response_body": {
+    "headers": { "X-Correlation-Id": "9b0f069a-...", "Content-Type": "application/json; charset=utf-8" },
+    "body": { "status": "success", "data": { "email": "a@b.c", "password": "***MASKED***", "id": "123" } },
+    "content_type": "application/json; charset=utf-8",
+    "content_length": 104
+  }
+}
+```
+
+Outgoing log เหมือนกันแต่ `message` = `"Outgoing request"`, `uri` = URL เต็ม, ไม่มี `remote_address`/`user_agent`
+และมี `"extra": { "direction": "outgoing" }`
+
+### คำอธิบาย Field
+
+| Field | หมายเหตุ |
+|---|---|
+| `@timestamp` | ISO 8601 + timezone ของเครื่อง (`YYYY-MM-DDTHH:mm:ss.SSS+07:00`) |
+| `@version` | `"1"` เสมอ |
+| `application` | `config.applicationName` |
+| `logger_name` | ชื่อที่ส่งให้ `new AppLogger(name)` |
+| `thread_name` | `main` (หรือ `worker-N` ถ้ารันใน worker thread) |
+| `level` / `level_value` | TRACE=5000 DEBUG=10000 INFO=20000 WARN=30000 ERROR=40000 |
+| `type` | `"application"` หรือ `"request"` |
+| `correlation_id` | จาก async context (`""` ถ้าไม่มี) |
+| `method`, `uri` | มีค่าเฉพาะ request log (application log เป็น `""`) |
+| `status_code`, `duration_ms` | เฉพาะ request log |
+| `remote_address`, `user_agent` | เฉพาะ incoming request log |
+| `request_body`, `response_body` | `headers`, `query_params`, `path_params`, `body`, `content_type`, `content_length` (application log เป็น `{}`) |
+| `extra` | extra ที่ merge แล้ว (ไม่มี key ถ้าว่าง) |
+| `error` | `class`, `message`, `stack_trace` (เฉพาะ `warnError`/`errorWithErr`) |
+
+ชื่อ header ใน log ถูกจัดรูปแบบเหมือน Go (`content-type` → `Content-Type`, `x-correlation-id` → `X-Correlation-Id`)
+
+---
+
+## API Reference
+
+| Export | ประเภท | เทียบกับ Go |
+|---|---|---|
+| `AppLogger` | class | `logger.AppLogger` |
+| `new AppLogger(name)` | constructor | `logger.New(name)` |
+| `new AppLogger(name, config)` | constructor | `logger.NewWithConfig(name, config)` |
+| `configureDefaults(config)` | function | `logger.ConfigureDefaults` |
+| `getDefaultConfig()` | function | `logger.GetDefaultConfig` |
+| `defaultConfig()` | function | `logger.DefaultConfig` |
+| `buildConfig(partial?)` | function | — (merge partial เข้ากับ default) |
+| `LevelValue` | const | `logger.LevelValue` |
+| `formatTimestamp(date)` | function | `logger.FormatTimestamp` |
+| `MaskingUtil` | class | `logger.MaskingUtil` |
+| `CorrelationIDHeader` | const | `logger.CorrelationIDHeader` |
+| `withCorrelationId(id, fn)` | function | `logger.WithCorrelationID` |
+| `getCorrelationId()` | function | `logger.GetCorrelationID` |
+| `generateCorrelationId()` | function | `logger.GenerateCorrelationID` |
+| `ensureCorrelationId()` | function | `logger.EnsureCorrelationID` |
+| `mergeExtras(extras)` | function | `mergeExtras` (internal ใน Go) |
+| `matchPattern` / `shouldSkip` | function | `matchPattern` / `shouldSkip` (internal ใน Go) |
+| `LoggingModule.forRoot(config?)` | Nest module | `ConfigureDefaults` + `r.Use(LoggingMiddleware)` (เลือก Express/Fastify เอง) |
+| `LoggingMiddleware` | Nest middleware class | `middleware.LoggingMiddleware(logger.New("LoggingMiddleware"))` |
+| `createLoggingMiddleware(log, config?)` | function | `middleware.LoggingMiddleware(log, config)` (Express) |
+| `createFastifyLoggingPlugin(log, config?)` | function | `middleware.LoggingMiddleware(log, config)` (Fastify plugin) |
+| `registerFastifyLogging(fastify, log, config?)` | function | เหมือนด้านบน แต่เรียก `addHook` ตรงๆ |
+| `createLoggingFetch(log, config?, baseFetch?)` | function | `httpclient.NewClient(log, config)` |
+| `LogEntry`, `ErrorInfo`, `RequestInfo`, `ResponseInfo`, `Config`, `ConfigInput`, ... | types | struct เดียวกัน |
+
+---
+
+## เทียบกับ Go version
+
+| เรื่อง | Go | NestJS |
+|---|---|---|
+| ส่ง context | `log.Info(ctx, "msg")` | `log.info('msg')` — correlation ID มาจาก `AsyncLocalStorage` อัตโนมัติ |
+| ชื่อ method | `Info`, `ErrorWithErr` | `info`, `errorWithErr` (camelCase) |
+| ชื่อ config | `RequestLogging.MaxBodySize` | `requestLogging.maxBodySize` |
+| Middleware | Gin `r.Use(...)` | `LoggingModule.forRoot()` (Express หรือ Fastify อัตโนมัติ) / `createLoggingMiddleware()` / `createFastifyLoggingPlugin()` |
+| HTTP client | `*http.Client` | `fetch` function |
+| `thread_name` | `goroutine-N` | `main` / `worker-N` |
+| `error.class` | `%T` เช่น `*errors.errorString` | ชื่อ class เช่น `Error`, `TypeError` |
+| `stack_trace` | stack ณ จุดที่เรียก log | stack ของ error ที่ส่งเข้ามา (มีประโยชน์กว่า) |
+| default config | อ่านตอน `New()` | อ่านทุกครั้งที่ log — logger ที่สร้างก่อน `configureDefaults` ก็ได้ค่าใหม่ |
+| `NewClient(log, nil)` | panic (config nil) | ใช้ default config |
+| query string ใน log | ไม่ mask | mask ด้วย `maskedFields` (`query_params` และ URL ขาออก) |
+| ลำดับ key ใน object ย่อย | เรียงตามตัวอักษร (Go map) | ตามลำดับที่ได้รับ (ค่าเหมือนกัน) |
+
+**ไม่รองรับ:** การแปลง log ภายในของ Nest
+(`[Nest] ... LOG [RoutesResolver]`) เป็น JSON — ถ้าต้องการปิด log เหล่านั้นใช้ `NestFactory.create(AppModule, { logger: ['error', 'warn'] })`
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build     # tsc → dist/
+npm test                 # compile + node --test (unit + NestJS e2e บน Express และ Fastify + Fastify ล้วน + fetch)
+npm run example          # รัน examples/nest-example บน Express ที่ port 8080
+npm run example:fastify  # รัน example เดียวกันบน Fastify
+```
+
+ทดลองยิง example:
+
+```bash
+curl 'localhost:8080/api/users?a=1&a=2' -H 'Authorization: Bearer x'
+curl localhost:8080/api/users/42
+curl -XPOST localhost:8080/api/users -H 'content-type: application/json' -d '{"email":"a@b.c","password":"p"}'
+curl -XPOST localhost:8080/api/users -H 'content-type: application/json' -H 'X-Correlation-ID: my-id' -d '{}'
+curl localhost:8080/api/external
+curl localhost:8080/health     # ไม่ถูก log (excludePatterns)
+```
+
+### โครงสร้าง
+
+```
+src/
+  logger/        # AppLogger, Config, LogEntry, MaskingUtil, correlation ID (AsyncLocalStorage)
+  middleware/    # LoggingMiddleware, createLoggingMiddleware (incoming, Express)
+  fastify/       # createFastifyLoggingPlugin, registerFastifyLogging (incoming, Fastify)
+  httpclient/    # createLoggingFetch (outgoing)
+  internal/      # incoming request tracker (ใช้ร่วม Express/Fastify), pattern matching, header/body helpers
+  logging.module.ts
+examples/nest-example/   # เทียบเท่า examples/gin-example ของ Go (main.ts = Express, main-fastify.ts = Fastify)
+test/                    # node:test — unit + e2e (ผ่านบน NestJS 10/11/12, Express 4/5, Fastify 4/5)
+```
+
+## License
+
+MIT