@lark-apaas/nestjs-common 0.0.1-alpha.1

package/README.md

@@ -0,0 +1,161 @@
+# @lark-apaas/nestjs-common
+
+提供可复用的 NestJS 通用能力与类型定义，当前内置请求级上下文服务 `RequestContextService`，用于在一次 HTTP 请求的生命周期内安全地读写上下文数据（如请求 ID、路径、方法、用户/租户/应用信息、IP 等）。
+
+## 特性
+
+- 请求级上下文（AsyncLocalStorage）
+  - 在同一请求链路中安全传递上下文数据
+  - 支持在中间件、拦截器、服务、控制器中读写
+- 纯粹的 NestJS 通用包
+  - 不依赖具体业务模块（例如日志、可观测），便于复用
+
+## 安装
+
+```bash
+yarn add @lark-apaas/nestjs-common
+```
+
+或使用 npm：
+
+```bash
+npm install @lark-apaas/nestjs-common
+```
+
+## 环境要求
+
+- Node.js >= 18.0.0
+- NestJS >= 10.4.20
+
+## 快速开始
+
+### 1. 在顶层模块中注册为单例 Provider（推荐）
+
+```ts
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { RequestContextService } from '@lark-apaas/nestjs-common';
+
+@Module({
+  providers: [RequestContextService],
+  exports: [RequestContextService],
+})
+export class AppModule {}
+```
+
+> 建议在应用的根模块或全局模块中注册为单例，以确保整个应用共享同一个 `AsyncLocalStorage` 实例。
+
+### 2. 在中间件入口写入请求上下文
+
+```ts
+// observable-context.middleware.ts（示例）
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import type { Request, Response, NextFunction } from 'express';
+import { randomUUID } from 'crypto';
+import { RequestContextService } from '@lark-apaas/nestjs-common';
+
+@Injectable()
+export class ObservableContextMiddleware implements NestMiddleware {
+  constructor(private readonly reqCtx: RequestContextService) {}
+
+  use(req: Request & { userContext?: any }, res: Response, next: NextFunction) {
+    const requestId = (req.headers['x-tt-log-id'] as string) || (req.headers['x-request-id'] as string) || randomUUID();
+    const path = req.originalUrl ?? req.url;
+    const uc = req.userContext ?? {};
+
+    res.setHeader('x-log-trace-id', requestId);
+
+    this.reqCtx.run(
+      {
+        requestId,
+        path,
+        method: req.method,
+        userId: uc.userId,
+        tenantId: uc.tenantId,
+        appId: uc.appId,
+        ip: (req.ip as string) ?? undefined,
+      },
+      () => next(),
+    );
+  }
+}
+```
+
+### 3. 在任意位置读取上下文
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { RequestContextService } from '@lark-apaas/nestjs-common';
+
+@Injectable()
+export class DemoService {
+  constructor(private readonly reqCtx: RequestContextService) {}
+
+  doSomething() {
+    const ctx = this.reqCtx.getContext();
+    // 或者精确获取某个键
+    const requestId = this.reqCtx.get('requestId');
+    // ... 使用上下文执行你的逻辑
+    return { requestId, path: ctx?.path, method: ctx?.method };
+  }
+}
+```
+
+## API 概览
+
+`RequestContextService` 源码位置：packages/server/nestjs-common/src/request-context.service.ts
+
+- `run(context, callback)`：在 `AsyncLocalStorage` 中启动一次上下文存储并执行回调。
+  - 参考：packages/server/nestjs-common/src/request-context.service.ts:15-20
+- `setContext(partial)`：在当前上下文中合并写入部分字段。
+  - 参考：packages/server/nestjs-common/src/request-context.service.ts:22-30
+- `getContext()`：读取当前完整上下文。
+  - 参考：packages/server/nestjs-common/src/request-context.service.ts:32-34
+- `get(key)`：读取当前上下文中的特定键。
+  - 参考：packages/server/nestjs-common/src/request-context.service.ts:36-38
+
+`RequestContextState` 默认字段：
+
+```ts
+interface RequestContextState {
+  requestId: string;
+  path?: string;
+  method?: string;
+  userId?: string;
+  appId?: string;
+  tenantId?: string;
+  ip?: string;
+  [key: string]: unknown;
+}
+```
+
+## 与其他模块的协作建议
+
+- 与日志/可观测模块协作
+  - 在 HTTP 入口（中间件）调用 `run(...)` 写入上下文；
+  - 在日志或可观测的记录点读取上下文并合并到结构化日志或埋点数据中。
+- 仅白名单传递敏感信息
+  - 避免直接把所有请求头写入上下文，建议只传递必要字段（如 trace-id、user-id、tenant-id、app-id）。
+
+## TypeScript 支持
+
+本包使用 TypeScript 编写并导出完整类型：
+
+```ts
+export { RequestContextService, type RequestContextState } from '@lark-apaas/nestjs-common';
+```
+
+如需在 `Express.Request` 上扩展 `userContext` 等业务字段，请在你自己的项目中通过 `declare global` 进行类型声明扩展。
+
+## 许可证
+
+MIT
+
+## 关键字
+
+- nestjs
+- common
+- context
+- als
+- server
+- typescript

package/dist/index.cjs

@@ -0,0 +1,98 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CommonModule: () => CommonModule,
+  RequestContextService: () => RequestContextService
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/request-context.service.ts
+var import_common = require("@nestjs/common");
+var import_async_hooks = require("async_hooks");
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+var RequestContextService = class {
+  static {
+    __name(this, "RequestContextService");
+  }
+  storage = new import_async_hooks.AsyncLocalStorage();
+  run(context, callback) {
+    const store = {
+      ...context
+    };
+    return this.storage.run(store, callback);
+  }
+  setContext(partial) {
+    const store = this.storage.getStore();
+    if (!store) {
+      return;
+    }
+    Object.assign(store, partial);
+  }
+  getContext() {
+    return this.storage.getStore();
+  }
+  get(key) {
+    return this.storage.getStore()?.[key];
+  }
+};
+RequestContextService = _ts_decorate([
+  (0, import_common.Injectable)()
+], RequestContextService);
+
+// src/module.ts
+var import_common2 = require("@nestjs/common");
+function _ts_decorate2(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+var CommonModule = class {
+  static {
+    __name(this, "CommonModule");
+  }
+};
+CommonModule = _ts_decorate2([
+  (0, import_common2.Global)(),
+  (0, import_common2.Module)({
+    providers: [
+      RequestContextService
+    ],
+    exports: [
+      RequestContextService
+    ]
+  })
+], CommonModule);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CommonModule,
+  RequestContextService
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/request-context.service.ts","../src/module.ts"],"sourcesContent":["export { RequestContextService, type RequestContextState } from './request-context.service';\nexport { CommonModule } from './module';\n","import { Injectable } from '@nestjs/common';\nimport { AsyncLocalStorage } from 'async_hooks';\n\nexport interface RequestContextState {\n  requestId: string;\n  path?: string;\n  method?: string;\n  userId?: string;\n  appId?: string;\n  tenantId?: string;\n  ip?: string;\n  [key: string]: unknown;\n}\n\n@Injectable()\nexport class RequestContextService {\n  private readonly storage = new AsyncLocalStorage<RequestContextState>();\n\n  run<T>(context: RequestContextState, callback: () => T): T {\n    const store = { ...context };\n    return this.storage.run(store, callback);\n  }\n\n  setContext(partial: Partial<RequestContextState>): void {\n    const store = this.storage.getStore();\n    if (!store) {\n      return;\n    }\n    Object.assign(store, partial);\n  }\n\n  getContext(): RequestContextState | undefined {\n    return this.storage.getStore();\n  }\n\n  get<K extends keyof RequestContextState>(key: K): RequestContextState[K] | undefined {\n    return this.storage.getStore()?.[key];\n  }\n}\n","import { Global, Module } from '@nestjs/common';\nimport { RequestContextService } from './request-context.service';\n\n@Global()\n@Module({\n  providers: [RequestContextService],\n  exports: [RequestContextService],\n})\nexport class CommonModule {}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;ACAA,oBAA2B;AAC3B,yBAAkC;;;;;;;;AAc3B,IAAMA,wBAAN,MAAMA;SAAAA;;;EACMC,UAAU,IAAIC,qCAAAA;EAE/BC,IAAOC,SAA8BC,UAAsB;AACzD,UAAMC,QAAQ;MAAE,GAAGF;IAAQ;AAC3B,WAAO,KAAKH,QAAQE,IAAIG,OAAOD,QAAAA;EACjC;EAEAE,WAAWC,SAA6C;AACtD,UAAMF,QAAQ,KAAKL,QAAQQ,SAAQ;AACnC,QAAI,CAACH,OAAO;AACV;IACF;AACAI,WAAOC,OAAOL,OAAOE,OAAAA;EACvB;EAEAI,aAA8C;AAC5C,WAAO,KAAKX,QAAQQ,SAAQ;EAC9B;EAEAI,IAAyCC,KAA4C;AACnF,WAAO,KAAKb,QAAQQ,SAAQ,IAAKK,GAAAA;EACnC;AACF;;;;;;ACtCA,IAAAC,iBAA+B;;;;;;;;AAQxB,IAAMC,eAAN,MAAMA;SAAAA;;;AAAc;;;;IAHzBC,WAAW;MAACC;;IACZC,SAAS;MAACD;;;;","names":["RequestContextService","storage","AsyncLocalStorage","run","context","callback","store","setContext","partial","getStore","Object","assign","getContext","get","key","import_common","CommonModule","providers","RequestContextService","exports"]}

package/dist/index.d.cts

@@ -0,0 +1,22 @@
+interface RequestContextState {
+    requestId: string;
+    path?: string;
+    method?: string;
+    userId?: string;
+    appId?: string;
+    tenantId?: string;
+    ip?: string;
+    [key: string]: unknown;
+}
+declare class RequestContextService {
+    private readonly storage;
+    run<T>(context: RequestContextState, callback: () => T): T;
+    setContext(partial: Partial<RequestContextState>): void;
+    getContext(): RequestContextState | undefined;
+    get<K extends keyof RequestContextState>(key: K): RequestContextState[K] | undefined;
+}
+
+declare class CommonModule {
+}
+
+export { CommonModule, RequestContextService, type RequestContextState };

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+interface RequestContextState {
+    requestId: string;
+    path?: string;
+    method?: string;
+    userId?: string;
+    appId?: string;
+    tenantId?: string;
+    ip?: string;
+    [key: string]: unknown;
+}
+declare class RequestContextService {
+    private readonly storage;
+    run<T>(context: RequestContextState, callback: () => T): T;
+    setContext(partial: Partial<RequestContextState>): void;
+    getContext(): RequestContextState | undefined;
+    get<K extends keyof RequestContextState>(key: K): RequestContextState[K] | undefined;
+}
+
+declare class CommonModule {
+}
+
+export { CommonModule, RequestContextService, type RequestContextState };

package/dist/index.js

@@ -0,0 +1,72 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/request-context.service.ts
+import { Injectable } from "@nestjs/common";
+import { AsyncLocalStorage } from "async_hooks";
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+var RequestContextService = class {
+  static {
+    __name(this, "RequestContextService");
+  }
+  storage = new AsyncLocalStorage();
+  run(context, callback) {
+    const store = {
+      ...context
+    };
+    return this.storage.run(store, callback);
+  }
+  setContext(partial) {
+    const store = this.storage.getStore();
+    if (!store) {
+      return;
+    }
+    Object.assign(store, partial);
+  }
+  getContext() {
+    return this.storage.getStore();
+  }
+  get(key) {
+    return this.storage.getStore()?.[key];
+  }
+};
+RequestContextService = _ts_decorate([
+  Injectable()
+], RequestContextService);
+
+// src/module.ts
+import { Global, Module } from "@nestjs/common";
+function _ts_decorate2(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+var CommonModule = class {
+  static {
+    __name(this, "CommonModule");
+  }
+};
+CommonModule = _ts_decorate2([
+  Global(),
+  Module({
+    providers: [
+      RequestContextService
+    ],
+    exports: [
+      RequestContextService
+    ]
+  })
+], CommonModule);
+export {
+  CommonModule,
+  RequestContextService
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/request-context.service.ts","../src/module.ts"],"sourcesContent":["import { Injectable } from '@nestjs/common';\nimport { AsyncLocalStorage } from 'async_hooks';\n\nexport interface RequestContextState {\n  requestId: string;\n  path?: string;\n  method?: string;\n  userId?: string;\n  appId?: string;\n  tenantId?: string;\n  ip?: string;\n  [key: string]: unknown;\n}\n\n@Injectable()\nexport class RequestContextService {\n  private readonly storage = new AsyncLocalStorage<RequestContextState>();\n\n  run<T>(context: RequestContextState, callback: () => T): T {\n    const store = { ...context };\n    return this.storage.run(store, callback);\n  }\n\n  setContext(partial: Partial<RequestContextState>): void {\n    const store = this.storage.getStore();\n    if (!store) {\n      return;\n    }\n    Object.assign(store, partial);\n  }\n\n  getContext(): RequestContextState | undefined {\n    return this.storage.getStore();\n  }\n\n  get<K extends keyof RequestContextState>(key: K): RequestContextState[K] | undefined {\n    return this.storage.getStore()?.[key];\n  }\n}\n","import { Global, Module } from '@nestjs/common';\nimport { RequestContextService } from './request-context.service';\n\n@Global()\n@Module({\n  providers: [RequestContextService],\n  exports: [RequestContextService],\n})\nexport class CommonModule {}\n"],"mappings":";;;;AAAA,SAASA,kBAAkB;AAC3B,SAASC,yBAAyB;;;;;;;;AAc3B,IAAMC,wBAAN,MAAMA;SAAAA;;;EACMC,UAAU,IAAIC,kBAAAA;EAE/BC,IAAOC,SAA8BC,UAAsB;AACzD,UAAMC,QAAQ;MAAE,GAAGF;IAAQ;AAC3B,WAAO,KAAKH,QAAQE,IAAIG,OAAOD,QAAAA;EACjC;EAEAE,WAAWC,SAA6C;AACtD,UAAMF,QAAQ,KAAKL,QAAQQ,SAAQ;AACnC,QAAI,CAACH,OAAO;AACV;IACF;AACAI,WAAOC,OAAOL,OAAOE,OAAAA;EACvB;EAEAI,aAA8C;AAC5C,WAAO,KAAKX,QAAQQ,SAAQ;EAC9B;EAEAI,IAAyCC,KAA4C;AACnF,WAAO,KAAKb,QAAQQ,SAAQ,IAAKK,GAAAA;EACnC;AACF;;;;;;ACtCA,SAASC,QAAQC,cAAc;;;;;;;;AAQxB,IAAMC,eAAN,MAAMA;SAAAA;;;AAAc;;;;IAHzBC,WAAW;MAACC;;IACZC,SAAS;MAACD;;;;","names":["Injectable","AsyncLocalStorage","RequestContextService","storage","AsyncLocalStorage","run","context","callback","store","setContext","partial","getStore","Object","assign","getContext","get","key","Global","Module","CommonModule","providers","RequestContextService","exports"]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@lark-apaas/nestjs-common",
+  "version": "0.0.1-alpha.1",
+  "description": "Common NestJS utilities",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "nestjs",
+    "common",
+    "context",
+    "als"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "echo 'ESLint skipped for TypeScript files'"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.4.20"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.4.20",
+    "@types/node": "^18.19.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.2.0"
+  }
+}