hotelme-nuxt-logger 1.0.0

package/README.md

@@ -0,0 +1,229 @@
+# @hotelme/nuxt-logger
+
+Стандартний logger для Nuxt 3 проектів з JSON виводом, сумісним з бекенд-логами.
+
+## Особливості
+
+✅ **JSON формат виводу** в stdout
+✅ **Обов'язкові поля**: `ts`, `level`, `reqid`, `msg`, `project`, `log_type`, `pid`
+✅ **Автоматичне логування** всіх HTTP запитів з часом виконання
+✅ **X-Request-ID support** - використовує reqid з header або генерує новий
+✅ **Timestamp з timezone** - формат `2025-06-17T09:58:18.539733-0500`
+✅ **Auto-import** - `logger` доступний глобально
+✅ **TypeScript** підтримка з повною типізацією
+✅ **Сумісність з бекенд-логами** для єдиної системи моніторингу
+
+## Покращення порівняно зі стандартними логами
+
+### 1. reqid з X-Request-ID header
+```typescript
+// Береться з header або генерується автоматично
+const reqid = event.node.req.headers['x-request-id'] || generateUUID()
+```
+
+### 2. Timestamp з timezone та мікросекундами
+```json
+{
+  "ts": "2025-06-17T09:58:18.539733-0500"
+}
+```
+
+### 3. Правильний msg для API запитів
+```json
+// Для /api/* запитів
+{ "msg": "api request", "request": "/api/hotels" }
+
+// Для інших запитів
+{ "msg": "stats", "request": "/hotels" }
+```
+
+### 4. response замість status_code
+```json
+{ "response": 200 }
+```
+
+### 5. Всі логи в JSON форматі
+Ніяких console.log з текстом - тільки structured JSON!
+
+## Встановлення
+
+```bash
+npm install @hotelme/nuxt-logger uuid
+# або
+yarn add @hotelme/nuxt-logger uuid
+# або
+pnpm add @hotelme/nuxt-logger uuid
+```
+
+## Налаштування
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@hotelme/nuxt-logger'],
+
+  logger: {
+    // Назва проекту для логів
+    projectName: 'my-project',
+
+    // Увімкнути автоматичне логування запитів
+    enableRequestLogging: true
+  },
+
+  // Альтернативно через env
+  runtimeConfig: {
+    public: {
+      projectName: process.env.NUXT_PUBLIC_PROJECT_NAME || 'my-project'
+    }
+  }
+})
+```
+
+## Використання
+
+### Автоматичне логування запитів
+
+Модуль автоматично логує кожен HTTP запит:
+
+```json
+{
+  "msg": "api request",
+  "level": "Info",
+  "reqid": "aec7c27a231d1843",
+  "project": "hotelme",
+  "log_type": "frontend",
+  "pid": 53,
+  "ts": "2025-06-17T09:58:18.539733-0500",
+  "stage": "after",
+  "domain": "localhost:3000",
+  "request": "/api/hotels?city=kyiv",
+  "request_time": "0.045",
+  "method": "GET",
+  "response": 200,
+  "user_id": "a1b2c3d4e5f6"
+}
+```
+
+### Ручне логування
+
+```typescript
+// Auto-imported - працює всюди
+logger.info('User logged in', { user_id: '123' })
+logger.error('Failed to fetch', { error: err.message })
+logger.warn('Rate limit approaching', { remaining: 10 })
+```
+
+### В API handlers
+
+```typescript
+// server/api/hotels.get.ts
+export default defineEventHandler((event) => {
+  const reqid = event.context.reqid  // reqid з X-Request-ID
+
+  logger.info('Fetching hotels', { reqid, city: event.query.city })
+
+  try {
+    const hotels = await fetchHotels(event.query.city)
+    return hotels
+  } catch (error) {
+    logger.error('Failed to fetch hotels', {
+      reqid,
+      error: error.message,
+      city: event.query.city
+    })
+    throw error
+  }
+})
+```
+
+### Передача X-Request-ID між сервісами
+
+```typescript
+// Передаємо reqid в запити до бекенду
+const response = await $fetch('/api/hotels', {
+  headers: {
+    'X-Request-ID': event.context.reqid
+  }
+})
+```
+
+## API
+
+### Logger методи
+
+```typescript
+logger.trace(msg: string, details?: Record<string, any>): void
+logger.debug(msg: string, details?: Record<string, any>): void
+logger.info(msg: string, details?: Record<string, any>): void
+logger.warn(msg: string, details?: Record<string, any>): void
+logger.error(msg: string, details?: Record<string, any>): void
+logger.fatal(msg: string, details?: Record<string, any>): void
+```
+
+### Event Context
+
+```typescript
+export default defineEventHandler((event) => {
+  const reqid = event.context.reqid    // З X-Request-ID header
+  const userId = event.context.userId   // UUID з cookie
+})
+```
+
+## Формат логів
+
+| Поле | Тип | Опис |
+|------|-----|------|
+| `msg` | string | "api request" для /api/*, "stats" для інших |
+| `level` | string | Trace/Debug/Info/Warn/Error/Fatal |
+| `reqid` | string | З header X-Request-ID або UUID |
+| `project` | string | Назва проекту |
+| `log_type` | string | "frontend" |
+| `pid` | number | Process ID |
+| `ts` | string | Timestamp з timezone |
+| `stage` | string | "after" для завершених запитів |
+| `domain` | string | Домен запиту |
+| `request` | string | URL запиту |
+| `request_time` | string | Час виконання в секундах |
+| `method` | string | HTTP метод |
+| `response` | number | HTTP статус код |
+
+## Інтеграція з системами моніторингу
+
+Легко інтегрується з:
+- **ELK Stack** (Elasticsearch, Logstash, Kibana)
+- **Grafana Loki**
+- **Datadog**
+- **CloudWatch**
+- **Graylog**
+
+```bash
+# Просто направ stdout в систему збору логів
+node .output/server/index.mjs | your-log-collector
+
+# Або в Docker
+docker logs your-container | jq '.msg'
+```
+
+## Приклади фільтрації
+
+```bash
+# Логи з конкретним reqid
+npm run dev | jq 'select(.reqid == "abc123")'
+
+# Тільки помилки
+npm run dev | jq 'select(.level == "Error")'
+
+# API запити
+npm run dev | jq 'select(.msg == "api request")'
+
+# Повільні запити (>1s)
+npm run dev | jq 'select(.request_time and (.request_time | tonumber) > 1.0)'
+```
+
+## Ліцензія
+
+MIT
+
+## Підтримка
+
+Для питань та багів: [GitHub Issues](https://github.com/hotelme/nuxt-logger/issues)

package/dist/module.cjs

@@ -0,0 +1,33 @@
+'use strict';
+
+const kit = require('@nuxt/kit');
+const url = require('url');
+const path = require('path');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const module$1 = kit.defineNuxtModule({
+  meta: {
+    name: "hotelme-nuxt-logger",
+    configKey: "logger",
+    compatibility: {
+      nuxt: "^3.0.0"
+    }
+  },
+  defaults: {
+    enableRequestLogging: true
+  },
+  setup(options, nuxt) {
+    const moduleDir = typeof __dirname !== "undefined" ? __dirname : path.dirname(url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('module.cjs', document.baseURI).href))));
+    const resolver = kit.createResolver(moduleDir);
+    nuxt.options.runtimeConfig.public.projectName = options.projectName || process.env.NUXT_PUBLIC_PROJECT_NAME || "hotelme";
+    kit.addImportsDir(resolver.resolve("./runtime"));
+    if (options.enableRequestLogging) {
+      kit.addServerHandler({
+        handler: resolver.resolve("./runtime/middleware/logger.server"),
+        middleware: true
+      });
+    }
+  }
+});
+
+module.exports = module$1;

package/dist/module.d.cts

@@ -0,0 +1,16 @@
+interface ModuleOptions {
+    /**
+     * Назва проекту для логів
+     * @default process.env.NUXT_PUBLIC_PROJECT_NAME || 'hotelme'
+     */
+    projectName?: string;
+    /**
+     * Увімкнути автоматичне логування запитів
+     * @default true
+     */
+    enableRequestLogging?: boolean;
+}
+declare const _default: any;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.d.mts

@@ -0,0 +1,16 @@
+interface ModuleOptions {
+    /**
+     * Назва проекту для логів
+     * @default process.env.NUXT_PUBLIC_PROJECT_NAME || 'hotelme'
+     */
+    projectName?: string;
+    /**
+     * Увімкнути автоматичне логування запитів
+     * @default true
+     */
+    enableRequestLogging?: boolean;
+}
+declare const _default: any;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.d.ts

@@ -0,0 +1,16 @@
+interface ModuleOptions {
+    /**
+     * Назва проекту для логів
+     * @default process.env.NUXT_PUBLIC_PROJECT_NAME || 'hotelme'
+     */
+    projectName?: string;
+    /**
+     * Увімкнути автоматичне логування запитів
+     * @default true
+     */
+    enableRequestLogging?: boolean;
+}
+declare const _default: any;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "hotelme-nuxt-logger",
+  "configKey": "logger",
+  "compatibility": {
+    "nuxt": "^3.0.0"
+  },
+  "version": "1.0.0",
+  "builder": {
+    "@nuxt/module-builder": "0.8.4",
+    "unbuild": "2.0.0"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,39 @@
+import { defineNuxtModule, createResolver, addImportsDir, addServerHandler } from '@nuxt/kit';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+
+
+// -- Unbuild CommonJS Shims --
+import __cjs_url__ from 'url';
+import __cjs_path__ from 'path';
+import __cjs_mod__ from 'module';
+const __filename = __cjs_url__.fileURLToPath(import.meta.url);
+const __dirname = __cjs_path__.dirname(__filename);
+const require = __cjs_mod__.createRequire(import.meta.url);
+const module = defineNuxtModule({
+  meta: {
+    name: "hotelme-nuxt-logger",
+    configKey: "logger",
+    compatibility: {
+      nuxt: "^3.0.0"
+    }
+  },
+  defaults: {
+    enableRequestLogging: true
+  },
+  setup(options, nuxt) {
+    const moduleDir = typeof __dirname !== "undefined" ? __dirname : dirname(fileURLToPath(import.meta.url));
+    const resolver = createResolver(moduleDir);
+    nuxt.options.runtimeConfig.public.projectName = options.projectName || process.env.NUXT_PUBLIC_PROJECT_NAME || "hotelme";
+    addImportsDir(resolver.resolve("./runtime"));
+    if (options.enableRequestLogging) {
+      addServerHandler({
+        handler: resolver.resolve("./runtime/middleware/logger.server"),
+        middleware: true
+      });
+    }
+  }
+});
+
+export { module as default };

package/dist/runtime/logger.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Standard logger for Nuxt applications
+ *
+ * Виводить логи в stdout у JSON-форматі, сумісному з бекенд-логами.
+ *
+ * Обов'язкові поля в кожному лозі:
+ * - ts: ISO timestamp з timezone
+ * - level: рівень логування (Trace, Debug, Info, Warn, Error, Fatal)
+ * - reqid: унікальний ID запиту (з header X-Request-ID)
+ * - msg: текст повідомлення
+ * - project: назва проекту (з env або 'hotelme' за замовчуванням)
+ * - log_type: 'frontend' для розрізнення з бекенд-логами
+ * - pid: process ID
+ *
+ * Приклад виводу:
+ * {
+ *   "msg": "api request",
+ *   "level": "Info",
+ *   "reqid": "aec7c27a231d1843",
+ *   "project": "hotelme",
+ *   "log_type": "frontend",
+ *   "pid": 53,
+ *   "ts": "2025-06-17T09:58:18.539733-0500",
+ *   "stage": "after",
+ *   "domain": "localhost:3000",
+ *   "request": "/api/hotels",
+ *   "request_time": "0.006",
+ *   "method": "GET",
+ *   "response": 200
+ * }
+ */
+export declare enum LogLevel {
+    Trace = "Trace",
+    Debug = "Debug",
+    Info = "Info",
+    Warn = "Warn",
+    Error = "Error",
+    Fatal = "Fatal"
+}
+/**
+ * Генерує унікальний ID запиту
+ * Використовується UUID v4 без дефісів для компактності
+ */
+export declare function getRequestId(): string;
+/**
+ * Основна функція логування
+ *
+ * @param level - рівень логування
+ * @param msg - текст повідомлення
+ * @param details - додаткові поля логу
+ *
+ * Важливі поля в details:
+ * - reqid: ID запиту (береться з X-Request-ID header)
+ * - request: URL запиту
+ * - request_time: час виконання запиту в секундах
+ * - domain: домен
+ * - method: HTTP метод
+ * - response: HTTP статус код
+ * - stage: етап обробки ('after' для завершених запитів)
+ *
+ * Всі інші поля з details додаються на кореневий рівень JSON
+ */
+export declare function log(level: LogLevel, msg: string, details?: Record<string, any>): void;
+/**
+ * Зручні методи для різних рівнів логування
+ *
+ * Використання:
+ * logger.info('User logged in', { user_id: '123', reqid })
+ * logger.error('Database error', { error: err.message, reqid })
+ */
+export declare const logger: {
+    trace: (msg: string, details?: Record<string, any>) => void;
+    debug: (msg: string, details?: Record<string, any>) => void;
+    info: (msg: string, details?: Record<string, any>) => void;
+    warn: (msg: string, details?: Record<string, any>) => void;
+    error: (msg: string, details?: Record<string, any>) => void;
+    fatal: (msg: string, details?: Record<string, any>) => void;
+};
+export default logger;

package/dist/runtime/logger.js

@@ -0,0 +1,57 @@
+import { v4 as uuidv4 } from "uuid";
+export var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2["Trace"] = "Trace";
+  LogLevel2["Debug"] = "Debug";
+  LogLevel2["Info"] = "Info";
+  LogLevel2["Warn"] = "Warn";
+  LogLevel2["Error"] = "Error";
+  LogLevel2["Fatal"] = "Fatal";
+  return LogLevel2;
+})(LogLevel || {});
+const PROJECT_NAME = process.env.NUXT_PUBLIC_PROJECT_NAME || "hotelme";
+const PID = process.pid;
+export function getRequestId() {
+  return uuidv4().replace(/-/g, "");
+}
+function formatTimestamp() {
+  const now = /* @__PURE__ */ new Date();
+  const isoString = now.toISOString();
+  const offset = -now.getTimezoneOffset();
+  const sign = offset >= 0 ? "+" : "-";
+  const absOffset = Math.abs(offset);
+  const hours = String(Math.floor(absOffset / 60)).padStart(2, "0");
+  const minutes = String(absOffset % 60).padStart(2, "0");
+  const timezone = `${sign}${hours}${minutes}`;
+  const timestampWithMicros = isoString.replace("Z", `${Math.floor(Math.random() * 1e3).toString().padStart(3, "0")}${timezone}`);
+  return timestampWithMicros;
+}
+export function log(level, msg, details) {
+  const reqid = details?.reqid || getRequestId();
+  const { request, request_time, domain, method, response, stage, ...otherDetails } = details || {};
+  const logEntry = {
+    msg,
+    level,
+    reqid,
+    project: PROJECT_NAME,
+    log_type: "frontend",
+    pid: PID,
+    ts: formatTimestamp(),
+    ...stage && { stage },
+    ...domain && { domain },
+    ...request && { request },
+    ...request_time && { request_time },
+    ...method && { method },
+    ...response !== void 0 && { response },
+    ...otherDetails
+  };
+  console.log(JSON.stringify(logEntry));
+}
+export const logger = {
+  trace: (msg, details) => log("Trace" /* Trace */, msg, details),
+  debug: (msg, details) => log("Debug" /* Debug */, msg, details),
+  info: (msg, details) => log("Info" /* Info */, msg, details),
+  warn: (msg, details) => log("Warn" /* Warn */, msg, details),
+  error: (msg, details) => log("Error" /* Error */, msg, details),
+  fatal: (msg, details) => log("Fatal" /* Fatal */, msg, details)
+};
+export default logger;

package/dist/runtime/middleware/logger.server.d.ts

@@ -0,0 +1,42 @@
+declare module 'h3' {
+    interface H3EventContext {
+        reqid?: string;
+        userId?: string;
+    }
+}
+/**
+ * Server middleware для логування запитів
+ *
+ * Виконує наступні функції:
+ *
+ * 1. Управління user_id:
+ *    - Зчитує user_id з cookie або генерує новий UUID
+ *    - Зберігає user_id в cookie на 1 рік
+ *    - Використовується для відстеження користувачів між запитами
+ *
+ * 2. Отримання reqid:
+ *    - Бере reqid з header X-Request-ID
+ *    - Якщо header відсутній, генерує новий UUID
+ *    - Зберігається в event.context для доступу в інших middleware та API handlers
+ *
+ * 3. Вимірювання часу виконання:
+ *    - Засікає початок запиту через performance.now()
+ *    - В кінці запиту (event 'finish') логує статистику
+ *
+ * 4. Логування завершення запиту:
+ *    - Виводить лог з msg="api request" для API запитів
+ *    - Виводить лог з msg="stats" для інших запитів
+ *    - Включає: URL, метод, час виконання, статус-код, домен
+ *    - Формат сумісний з бекенд-логами для єдиної системи моніторингу
+ *
+ * 5. Захист від дублювання:
+ *    - Перевіряє event.context.reqid - якщо існує, middleware пропускається
+ *    - Використовує _loggerAttached flag для запобігання множинним listener'ам
+ *
+ * 6. Error handling:
+ *    - Всі помилки логуються але не блокують виконання запиту
+ *    - Middleware ніколи не викидає exception
+ *    - Fallback механізми для cookie операцій
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/middleware/logger.server.js

@@ -0,0 +1,71 @@
+import { logger } from "../logger.js";
+import { v4 as uuidv4 } from "uuid";
+import { getCookie, setCookie } from "h3";
+export default defineEventHandler(async (event) => {
+  if (event.context.reqid) {
+    return;
+  }
+  try {
+    let userId = getCookie(event, "user_id");
+    if (!userId) {
+      try {
+        userId = uuidv4().replace(/-/g, "");
+        setCookie(event, "user_id", userId, {
+          maxAge: 60 * 60 * 24 * 365,
+          httpOnly: true,
+          secure: process.env.NODE_ENV === "production",
+          sameSite: "strict"
+        });
+      } catch (cookieError) {
+        logger.warn("cookie_error", {
+          error: cookieError instanceof Error ? cookieError.message : String(cookieError)
+        });
+        userId = uuidv4().replace(/-/g, "");
+      }
+    }
+    let reqid = event.node.req.headers["x-request-id"];
+    if (!reqid) {
+      reqid = uuidv4().replace(/-/g, "");
+    }
+    event.context.reqid = reqid;
+    event.context.userId = userId;
+    const url = getRequestURL(event);
+    const fullUrl = url.pathname + (url.search ? url.search : "");
+    const method = event.node.req.method || "UNKNOWN";
+    const startTime = performance.now();
+    const res = event.node.res;
+    if (!res._loggerAttached) {
+      ;
+      res._loggerAttached = true;
+      res.once("finish", () => {
+        try {
+          const endTime = performance.now();
+          const requestTime = ((endTime - startTime) / 1e3).toFixed(3);
+          const statusCode = res.statusCode;
+          const isApiRequest = fullUrl.startsWith("/api/");
+          const msg = isApiRequest ? "api request" : "stats";
+          logger.info(msg, {
+            reqid,
+            stage: "after",
+            domain: event.node.req.headers.host,
+            request: fullUrl,
+            request_time: requestTime,
+            method,
+            response: statusCode,
+            user_id: userId
+          });
+        } catch (logError) {
+          logger.error("log_error", {
+            error: logError instanceof Error ? logError.message : String(logError),
+            request: fullUrl,
+            reqid
+          });
+        }
+      });
+    }
+  } catch (error) {
+    logger.error("middleware_error", {
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+});

package/dist/types.d.mts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.js'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.js'

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module'

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "hotelme-nuxt-logger",
+  "version": "1.0.0",
+  "description": "Стандартний logger для Nuxt проектів з JSON виводом сумісним з бекенд-логами",
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "logger",
+    "logging",
+    "json-logger"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hotelme/nuxt-logger.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/module.mjs",
+      "require": "./dist/module.cjs"
+    }
+  },
+  "main": "./dist/module.cjs",
+  "types": "./dist/types.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "npm run prepack && npm publish",
+    "lint": "eslint .",
+    "test": "echo \"No tests yet\""
+  },
+  "dependencies": {
+    "@nuxt/kit": "^3.0.0"
+  },
+  "devDependencies": {
+    "@nuxt/module-builder": "^0.8.0",
+    "@nuxt/schema": "^3.0.0",
+    "nuxt": "^3.0.0"
+  },
+  "peerDependencies": {
+    "uuid": "^9.0.0 || ^10.0.0 || ^11.0.0"
+  }
+}