@jnpt/nest-logging 1.0.0 → 1.1.0

package/README.md

@@ -9,7 +9,7 @@ Library สำหรับทำ **structured JSON logging** ใน NestJS (ท
 - 📝 **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 ต่อ
+- 📤 **Outgoing Request Logging** — inject `HttpClient` ผ่าน `HttpClientModule` (Dynamic Module แบบ `@nestjs/axios`) หรือใช้ `fetch` ที่มี log ก็ได้ พร้อมส่ง 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
@@ -37,27 +37,43 @@ Library สำหรับทำ **structured JSON logging** ใน NestJS (ท
 
 ## Installation
 
-### 1. ติดตั้ง package
+### 1. ติดตั้ง package จาก npm (แนะนำ)
 
-package นี้ชื่อ `@jnpt/nest-logging` (แก้ชื่อได้ที่ `package.json`) เลือกวิธีใดวิธีหนึ่ง:
+package อยู่บน npm: [`@jnpt/nest-logging`](https://www.npmjs.com/package/@jnpt/nest-logging)
 
 ```bash
-# ก) ติดตั้งจาก registry (หลัง publish ด้วย `npm publish --access public`)
 npm install @jnpt/nest-logging
+# หรือ
+yarn add @jnpt/nest-logging
+# หรือ
+pnpm add @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
+ถ้าใช้ NestJS บน Fastify ต้องติดตั้ง adapter ของ Nest ด้วย (ถ้ามีอยู่แล้วก็ข้ามได้):
 
-# ค) ติดตั้งจากโฟลเดอร์ในเครื่อง (ระหว่างพัฒนา)
-npm install /Volumes/JP/Projects/Loggings/nest_logging
+```bash
+npm install @nestjs/platform-fastify
+```
 
-# ง) ติดตั้งจากไฟล์ 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
+ระบุ version ได้ เช่น `npm install @jnpt/nest-logging@1.0.0`, ดู version ทั้งหมดด้วย `npm view @jnpt/nest-logging versions`
+
+#### วิธีอื่น (ไม่ผ่าน npm registry)
+
+```bash
+# ก) จาก GitHub (ระบุ tag/branch ได้หลัง #)
+npm install github:jnpt-nestjs-templates/logging#main
+
+# ข) จากโฟลเดอร์ในเครื่อง (ระหว่างพัฒนา library)
+npm install /path/to/nest_logging
+
+# ค) จากไฟล์ tarball
+cd /path/to/nest_logging && npm pack           # ได้ไฟล์ jnpt-nest-logging-<version>.tgz
+cd /path/to/your-nest-app && npm install /path/to/jnpt-nest-logging-<version>.tgz
 ```
 
-> วิธี ข/ค/ง จะ build ให้อัตโนมัติผ่าน script `prepare` (`tsc` → `dist/`)
+> วิธี ก/ข/ค จะ build `dist/` ผ่าน script `prepare` ตอนติดตั้ง
+> **npm 12 ขึ้นไป:** ติดตั้งจาก git ต้องใส่ `--allow-git=all` และต้องอนุญาต install script ก่อนด้วย
+> `npm install-scripts approve @jnpt/nest-logging` ไม่งั้น `prepare` จะถูกบล็อกและไม่มี `dist/` — ติดตั้งจาก npm registry ไม่เจอปัญหานี้
 
 ### 2. Requirements
 
@@ -391,53 +407,100 @@ app.use(createLoggingMiddleware(new AppLogger('main')));
 
 ## Outgoing Request Logging (HTTP Client)
 
-`createLoggingFetch(logger, config?, baseFetch?)` คืนค่า function ที่ใช้แทน `fetch` ได้ทันที (เทียบเท่า `httpclient.NewClient` ของ Go)
+### แบบที่ 1 (แนะนำสำหรับ NestJS) — `HttpClientModule` + inject `HttpClient`
 
-### แบบง่าย (ใช้ default config)
+ใช้เหมือน `HttpModule` / `HttpService` ของ NestJS: register module ครั้งเดียว แล้ว inject `HttpClient` ผ่าน constructor
+(`HttpClientModule` สร้างด้วย [`ConfigurableModuleBuilder`](https://docs.nestjs.com/fundamentals/dynamic-modules#configurable-module-builder))
 
 ```ts
-import { AppLogger, createLoggingFetch } from '@jnpt/nest-logging';
-
-const log = new AppLogger('MyService');
-const fetch = createLoggingFetch(log);
-```
-
-### แบบกำหนด config เอง
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { HttpClientModule, LoggingModule } from '@jnpt/nest-logging';
 
-```ts
-const fetch = createLoggingFetch(log, {
-  applicationName: 'my-service',
-  requestLogging: { logBody: true, logResponseBody: true },
-});
+@Module({
+  imports: [
+    LoggingModule.forRoot({ applicationName: 'my-service' }),
+    HttpClientModule.register({
+      baseUrl: 'https://jsonplaceholder.typicode.com', // optional — ใช้กับ URL แบบ relative
+      headers: { 'X-Api-Key': process.env.API_KEY! },  // optional — ส่งทุก request
+    }),
+  ],
+  providers: [TodoClient],
+})
+export class AppModule {}
 ```
 
-### ใช้ใน NestJS service
-
 ```ts
+// todo.client.ts
 import { Injectable } from '@nestjs/common';
-import { AppLogger, createLoggingFetch } from '@jnpt/nest-logging';
+import { HttpClient } from '@jnpt/nest-logging';
 
 @Injectable()
 export class TodoClient {
-  private readonly log = new AppLogger(TodoClient.name);
-  private readonly fetch = createLoggingFetch(this.log);
+  constructor(private readonly http: HttpClient) {}
 
   async getTodo(id: number) {
-    const res = await this.fetch(`https://jsonplaceholder.typicode.com/todos/${id}`);
+    const res = await this.http.get(`/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),
-    });
+  async createTodo(todo: { title: string }) {
+    const res = await this.http.post('/todos', todo); // object → JSON + Content-Type: application/json ให้อัตโนมัติ
     return res.json();
   }
 }
 ```
 
+**Options ของ `register()` / ที่ `useFactory` คืนค่า** (ทุกตัว optional)
+
+| Option | ความหมาย |
+|---|---|
+| `baseUrl` | prefix ของ URL แบบ relative (`'/todos/1'` → `baseUrl + '/todos/1'`); URL เต็ม (`https://...`) ใช้ตามเดิม |
+| `headers` | header ที่ส่งทุก request (header ที่ส่งตอนเรียกจะทับ) |
+| `loggerName` | `logger_name` ของ log ขาออก (default `"HttpClient"`) |
+| `config` | logging config เฉพาะ client นี้ (default: config จาก `LoggingModule.forRoot`) |
+| `fetch` | fetch implementation อื่น (default: global `fetch`) |
+| `isGlobal` | `true` = ใช้ได้ทุก module โดยไม่ต้อง import ซ้ำ (เฉพาะ `register` / `registerAsync`) |
+
+**อ่าน options จาก `ConfigService`** — `registerAsync` รองรับ `useFactory` / `useClass` / `useExisting` + `imports` / `inject` ตามมาตรฐาน Nest
+
+```ts
+HttpClientModule.registerAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({ baseUrl: config.get('TODO_API_URL') }),
+})
+```
+
+**Methods ของ `HttpClient`** — ทุกตัวคืน `Promise<Response>` (fetch Response มาตรฐาน) และเหมือน `fetch` คือ **ไม่ throw เมื่อได้ 4xx/5xx** (เช็ค `res.ok` เอง) แต่ throw เมื่อ network error
+
+| Method | หมายเหตุ |
+|---|---|
+| `get(url, init?)`, `head(url, init?)`, `delete(url, init?)` | `init` = `RequestInit` ของ fetch (headers, signal, ...) |
+| `post(url, body?, init?)`, `put(...)`, `patch(...)` | `body` เป็น object/array/number/boolean → ส่งเป็น JSON; string / `Buffer` / `Blob` / `URLSearchParams` / `FormData` / stream → ส่งตามเดิม |
+| `request(url, init)` | เหมือน `fetch(url, init)` |
+
+ต้องการหลาย client (คนละ `baseUrl`) → สร้าง provider เอง เช่น
+`{ provide: 'PAYMENT_HTTP', useFactory: () => new HttpClient({ baseUrl: 'https://pay.example.com' }) }`
+และใช้นอก NestJS ได้ด้วย `new HttpClient(options)`
+
+### แบบที่ 2 — `createLoggingFetch` (fetch function)
+
+`createLoggingFetch(logger, config?, baseFetch?)` คืนค่า function ที่ใช้แทน `fetch` ได้ทันที (เทียบเท่า `httpclient.NewClient` ของ Go) — `HttpClient` ด้านบนก็ใช้ตัวนี้ข้างใน
+
+```ts
+import { AppLogger, createLoggingFetch } from '@jnpt/nest-logging';
+
+const log = new AppLogger('MyService');
+const fetch = createLoggingFetch(log); // ใช้ default config
+
+// หรือกำหนด config เอง
+const fetchWithConfig = createLoggingFetch(log, {
+  applicationName: 'my-service',
+  requestLogging: { logBody: true, logResponseBody: true },
+});
+```
+
 ### ทำอะไรบ้าง
 
 1. ใช้ correlation ID ของ request ปัจจุบัน (ถ้าไม่มี เช่นเรียกจาก cron job จะสร้างใหม่) แล้วใส่ header `X-Correlation-ID`
@@ -708,6 +771,8 @@ Outgoing log เหมือนกันแต่ `message` = `"Outgoing request
 | `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` ตรงๆ |
+| `HttpClientModule.register(options)` / `.registerAsync(...)` | Nest dynamic module | — (provide `HttpClient`) |
+| `HttpClient` | injectable class | `httpclient.NewClient(log, config)` |
 | `createLoggingFetch(log, config?, baseFetch?)` | function | `httpclient.NewClient(log, config)` |
 | `LogEntry`, `ErrorInfo`, `RequestInfo`, `ResponseInfo`, `Config`, `ConfigInput`, ... | types | struct เดียวกัน |
 
@@ -721,7 +786,7 @@ Outgoing log เหมือนกันแต่ `message` = `"Outgoing request
 | ชื่อ 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 |
+| HTTP client | `*http.Client` | `HttpClient` (inject ผ่าน `HttpClientModule`) หรือ `fetch` function |
 | `thread_name` | `goroutine-N` | `main` / `worker-N` |
 | `error.class` | `%T` เช่น `*errors.errorString` | ชื่อ class เช่น `Error`, `TypeError` |
 | `stack_trace` | stack ณ จุดที่เรียก log | stack ของ error ที่ส่งเข้ามา (มีประโยชน์กว่า) |
@@ -740,7 +805,7 @@ Outgoing log เหมือนกันแต่ `message` = `"Outgoing request
 ```bash
 npm install
 npm run build     # tsc → dist/
-npm test                 # compile + node --test (unit + NestJS e2e บน Express และ Fastify + Fastify ล้วน + fetch)
+npm test                 # compile + node --test (unit + NestJS e2e บน Express และ Fastify + Fastify ล้วน + fetch + HttpClientModule)
 npm run example          # รัน examples/nest-example บน Express ที่ port 8080
 npm run example:fastify  # รัน example เดียวกันบน Fastify
 ```
@@ -763,7 +828,7 @@ src/
   logger/        # AppLogger, Config, LogEntry, MaskingUtil, correlation ID (AsyncLocalStorage)
   middleware/    # LoggingMiddleware, createLoggingMiddleware (incoming, Express)
   fastify/       # createFastifyLoggingPlugin, registerFastifyLogging (incoming, Fastify)
-  httpclient/    # createLoggingFetch (outgoing)
+  httpclient/    # HttpClient, HttpClientModule, 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)

package/dist/httpclient/http-client.d.ts

@@ -0,0 +1,23 @@
+import type { ConfigInput } from '../logger/types';
+import { type FetchFn } from './logging-fetch';
+export interface HttpClientOptions {
+    baseUrl?: string;
+    headers?: RequestInit['headers'];
+    loggerName?: string;
+    config?: ConfigInput | null;
+    fetch?: FetchFn;
+}
+export type HttpBody = RequestInit['body'] | Record<string, unknown> | unknown[] | number | boolean;
+export declare class HttpClient {
+    private readonly options;
+    private readonly fetchFn;
+    constructor(options?: HttpClientOptions);
+    request(url: string | URL, init?: RequestInit): Promise<Response>;
+    get(url: string | URL, init?: RequestInit): Promise<Response>;
+    head(url: string | URL, init?: RequestInit): Promise<Response>;
+    delete(url: string | URL, init?: RequestInit): Promise<Response>;
+    post(url: string | URL, body?: HttpBody, init?: RequestInit): Promise<Response>;
+    put(url: string | URL, body?: HttpBody, init?: RequestInit): Promise<Response>;
+    patch(url: string | URL, body?: HttpBody, init?: RequestInit): Promise<Response>;
+    private resolveUrl;
+}

package/dist/httpclient/http-client.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const logger_1 = require("../logger/logger");
+const logging_fetch_1 = require("./logging-fetch");
+// HttpClient is an injectable HTTP client (via HttpClientModule) built on createLoggingFetch:
+// every call propagates X-Correlation-ID and is logged as an outgoing request.
+// Methods resolve to a standard fetch Response and, like fetch, do not throw on 4xx/5xx.
+class HttpClient {
+    options;
+    fetchFn;
+    constructor(options = {}) {
+        this.options = options;
+        const log = new logger_1.AppLogger(options.loggerName ?? 'HttpClient');
+        this.fetchFn = (0, logging_fetch_1.createLoggingFetch)(log, options.config, options.fetch);
+    }
+    request(url, init = {}) {
+        const headers = new Headers(this.options.headers);
+        new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+        return this.fetchFn(this.resolveUrl(url), { ...init, headers });
+    }
+    get(url, init) {
+        return this.request(url, { ...init, method: 'GET' });
+    }
+    head(url, init) {
+        return this.request(url, { ...init, method: 'HEAD' });
+    }
+    delete(url, init) {
+        return this.request(url, { ...init, method: 'DELETE' });
+    }
+    post(url, body, init) {
+        return this.request(url, withBody('POST', body, init));
+    }
+    put(url, body, init) {
+        return this.request(url, withBody('PUT', body, init));
+    }
+    patch(url, body, init) {
+        return this.request(url, withBody('PATCH', body, init));
+    }
+    resolveUrl(url) {
+        const { baseUrl } = this.options;
+        if (!baseUrl || typeof url !== 'string' || /^[a-z][a-z\d+.-]*:/i.test(url))
+            return url;
+        return `${baseUrl.replace(/\/+$/, '')}/${url.replace(/^\/+/, '')}`;
+    }
+}
+exports.HttpClient = HttpClient;
+function withBody(method, body, init = {}) {
+    if (body === undefined)
+        return { ...init, method };
+    if (isFetchBody(body))
+        return { ...init, method, body };
+    const headers = new Headers(init.headers);
+    if (!headers.has('content-type'))
+        headers.set('Content-Type', 'application/json');
+    return { ...init, method, headers, body: JSON.stringify(body) };
+}
+function isFetchBody(body) {
+    return body === null || typeof body === 'string' || body instanceof ArrayBuffer || ArrayBuffer.isView(body)
+        || body instanceof Blob || body instanceof URLSearchParams || body instanceof FormData
+        || body instanceof ReadableStream;
+}

package/dist/httpclient/http-client.module.d.ts

@@ -0,0 +1,10 @@
+import type { ConfigurableModuleCls } from '@nestjs/common';
+import { type HttpClientOptions } from './http-client';
+export interface HttpClientModuleExtras {
+    isGlobal?: boolean;
+}
+type HttpClientModuleBase = ConfigurableModuleCls<HttpClientOptions, 'register', 'create', HttpClientModuleExtras>;
+declare const HttpClientModule_base: HttpClientModuleBase;
+export declare class HttpClientModule extends HttpClientModule_base {
+}
+export {};

package/dist/httpclient/http-client.module.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClientModule = void 0;
+const http_client_1 = require("./http-client");
+// HttpClientModule.register(options) / registerAsync({ useFactory, inject, ... }) provides HttpClient,
+// built with NestJS ConfigurableModuleBuilder. @nestjs/common is required at load time only when it is
+// installed, so the rest of the package keeps working in plain Express / Fastify apps.
+function buildBase() {
+    let common;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        common = require('@nestjs/common');
+    }
+    catch {
+        const fail = () => {
+            throw new Error('HttpClientModule requires @nestjs/common; use new HttpClient(options) without NestJS');
+        };
+        return class {
+            static register = fail;
+            static registerAsync = fail;
+        };
+    }
+    const built = new common.ConfigurableModuleBuilder({ moduleName: 'HttpClient' })
+        .setClassMethodName('register')
+        .setExtras({ isGlobal: false }, (definition, extras) => ({
+        ...definition,
+        global: extras.isGlobal,
+        providers: [
+            ...(definition.providers ?? []),
+            { provide: http_client_1.HttpClient, useFactory: (options) => new http_client_1.HttpClient(options), inject: [optionsToken] },
+        ],
+        exports: [http_client_1.HttpClient],
+    }))
+        .build();
+    const optionsToken = built.MODULE_OPTIONS_TOKEN;
+    return built.ConfigurableModuleClass;
+}
+class HttpClientModule extends buildBase() {
+}
+exports.HttpClientModule = HttpClientModule;

package/dist/index.d.ts

@@ -6,4 +6,6 @@ export { matchPattern, shouldSkip } from './internal/http';
 export { createLoggingMiddleware, LoggingMiddleware, type HttpRequest, type HttpResponse, type NextFunction, } from './middleware/logging.middleware';
 export { createFastifyLoggingPlugin, registerFastifyLogging, type FastifyInstanceLike, type FastifyReplyLike, type FastifyRequestLike, } from './fastify/fastify-logging';
 export { createLoggingFetch, type FetchFn } from './httpclient/logging-fetch';
+export { HttpClient, type HttpBody, type HttpClientOptions } from './httpclient/http-client';
+export { HttpClientModule, type HttpClientModuleExtras } from './httpclient/http-client.module';
 export { LoggingModule } from './logging.module';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LoggingModule = exports.createLoggingFetch = exports.registerFastifyLogging = exports.createFastifyLoggingPlugin = exports.LoggingMiddleware = exports.createLoggingMiddleware = exports.shouldSkip = exports.matchPattern = exports.mergeExtras = exports.getDefaultConfig = exports.configureDefaults = exports.AppLogger = exports.MaskingUtil = void 0;
+exports.LoggingModule = exports.HttpClientModule = exports.HttpClient = exports.createLoggingFetch = exports.registerFastifyLogging = exports.createFastifyLoggingPlugin = exports.LoggingMiddleware = exports.createLoggingMiddleware = exports.shouldSkip = exports.matchPattern = exports.mergeExtras = exports.getDefaultConfig = exports.configureDefaults = exports.AppLogger = exports.MaskingUtil = void 0;
 __exportStar(require("./logger/types"), exports);
 __exportStar(require("./logger/context"), exports);
 var masking_1 = require("./logger/masking");
@@ -35,5 +35,9 @@ Object.defineProperty(exports, "createFastifyLoggingPlugin", { enumerable: true,
 Object.defineProperty(exports, "registerFastifyLogging", { enumerable: true, get: function () { return fastify_logging_1.registerFastifyLogging; } });
 var logging_fetch_1 = require("./httpclient/logging-fetch");
 Object.defineProperty(exports, "createLoggingFetch", { enumerable: true, get: function () { return logging_fetch_1.createLoggingFetch; } });
+var http_client_1 = require("./httpclient/http-client");
+Object.defineProperty(exports, "HttpClient", { enumerable: true, get: function () { return http_client_1.HttpClient; } });
+var http_client_module_1 = require("./httpclient/http-client.module");
+Object.defineProperty(exports, "HttpClientModule", { enumerable: true, get: function () { return http_client_module_1.HttpClientModule; } });
 var logging_module_1 = require("./logging.module");
 Object.defineProperty(exports, "LoggingModule", { enumerable: true, get: function () { return logging_module_1.LoggingModule; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jnpt/nest-logging",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Structured JSON logging for NestJS on Express or Fastify (port of github.com/jnpt-golangs/logging): application + request logs, correlation ID, masking, outgoing HTTP logging.",
   "license": "MIT",
   "repository": {