@kcuf/sls-logger-base 0.0.1

package/dist/types/class/sls-pipe.d.ts

@@ -0,0 +1,27 @@
+import { ISlsLogPayload, ISlsPipeOptions, ILogSender } from '../types';
+/**
+ * SLS 日志管道，用于在一定的时间内积压日志，以避免造成业务请求性能问题
+ */
+export default class SlsPipe {
+    private readonly sender;
+    private readonly options;
+    private queue;
+    private timer;
+    private silent;
+    constructor(sender: ILogSender, options: ISlsPipeOptions);
+    /**
+     * 将日志推入队列，并通知发送
+     */
+    pipe(payload: ISlsLogPayload, instant?: boolean): void;
+    private signalSend;
+    /**
+     * 真正发送日志
+     */
+    private sendLogs;
+    /**
+     * 把队列中的日志全部发送并重置队列
+     */
+    private clearQueue;
+    private clearTimer;
+    private refreshTimer;
+}

package/dist/types/const/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 合并日志的最外层的 topic
+ */
+export declare const TOPIC_MERGED = "SLS_MERGED";
+/**
+ * 定死的 API 版本，GET 的时候为参数 `APIVersion`，POST 的时候为 header `x-log-apiversion`
+ */
+export declare const API_VERSION = "0.6.0";
+export declare const PIPE_SILENT_TIME = 5000;
+export declare const PIPE_WAIT_TIME = 200;
+export declare const PIPE_MAX_CHUNK = 50;

package/dist/types/factory/create-logger.d.ts

@@ -0,0 +1,5 @@
+import { ICreateLoggerOptions, ISlsLogger, ILogSender } from '../types';
+/**
+ * 创建 Logger 方法
+ */
+export default function createLogger(sender: ILogSender, options: ICreateLoggerOptions): ISlsLogger;

package/dist/types/factory/generate-create-logger.d.ts

@@ -0,0 +1,7 @@
+import { ILogSender, ICreateLogger, IGenerateCreateLoggerOptions } from '../types';
+/**
+ * 创建 `createLogger` 方法的方法，对期望扩展默认参数的场景做了规范。
+ *
+ * 一般不会在项目中直接使用，而是用来写可复用 npm 包。
+ */
+export default function generateCreateLogger(sender: ILogSender, { defaultParams: factoryDefaultParams, shouldIgnore: factoryShouldIgnore }: IGenerateCreateLoggerOptions): ICreateLogger;

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { default } from './factory/create-logger';
+export { default as generateCreateLoggerBase } from './factory/generate-create-logger';
+export type { ICreateLogger as CreateLogger, ICreateLoggerOptions as CreateLoggerOptions, IGenerateCreateLoggerOptions as GenerateCreateLoggerOptions, ISlsLogger as SlsLogger, ISlsLogOptions as SlsLogOptions, ISlsLogOptionsQuick as SlsLogOptionsQuick, ISlsPostBody as SlsPostBody } from './types';

package/dist/types/types/common.d.ts

@@ -0,0 +1,32 @@
+export interface IDefaultParams {
+    (): Record<string, unknown>;
+}
+export type TDefaultParams = Record<string, unknown> | IDefaultParams;
+export interface IShouldIgnore {
+    (): void | boolean;
+}
+/**
+ * 真正发送请求的实现逻辑（以支持多平台的需求），注意必需用 POST
+ */
+export interface ILogSender {
+    (trackUrl: string, body: string, headers: Record<string, string>): void;
+}
+/**
+ * 用于在 flattenObject 的时候忽略部分属性
+ *
+ * - 默认忽略所有以 `_` 为前缀的属性
+ * - `string` 等于 `key` 则忽略
+ * - `string[]` 包含 `key` 则忽略
+ * - 方法，可用 `path` 进行判断（注意这里的 `path` 和 `prefix` 没有关系）
+ */
+export type TFlattenIgnore = string | string[] | {
+    (key: string, value: unknown, path: string): boolean;
+};
+export interface ISlsLogPayload {
+    __topic__: string;
+    [k: string]: unknown;
+}
+export interface ISlsPostBody {
+    __topic__: string;
+    __logs__: Record<string, string>[];
+}

package/dist/types/types/factory.d.ts

@@ -0,0 +1,30 @@
+import { ICreateLoggerOptions, ISlsLogOptionsQuick, ISlsLogOptions } from './options';
+export type TLogArgs = [string, Record<string, unknown>?] | [ISlsLogOptions, string, Record<string, unknown>?];
+export type TLogQuickArgs = [string, Record<string, unknown>?] | [ISlsLogOptionsQuick, string, Record<string, unknown>?];
+export interface ISlsLogFn {
+    (topic: string): void;
+    <P extends object>(topic: string, payload: P): void;
+    (options: ISlsLogOptions, topic: string): void;
+    <P extends object>(options: ISlsLogOptions, topic: string, payload: P): void;
+}
+export interface ISlsLogFnQuick {
+    (topic: string): void;
+    <P extends object>(topic: string, payload: P): void;
+    (options: ISlsLogOptionsQuick, topic: string): void;
+    <P extends object>(options: ISlsLogOptionsQuick, topic: string, payload: P): void;
+}
+export interface ISlsLogger {
+    (topic: string): void;
+    <P extends object>(topic: string, payload: P): void;
+    (options: ISlsLogOptions, topic: string): void;
+    <P extends object>(options: ISlsLogOptions, topic: string, payload: P): void;
+    debug: ISlsLogFnQuick;
+    log: ISlsLogFnQuick;
+    info: ISlsLogFnQuick;
+    warn: ISlsLogFnQuick;
+    error: ISlsLogFnQuick;
+    fatal: ISlsLogFnQuick;
+}
+export interface ICreateLogger {
+    (options: ICreateLoggerOptions): ISlsLogger;
+}

package/dist/types/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './common';
+export * from './options';
+export * from './factory';

package/dist/types/types/options.d.ts

@@ -0,0 +1,123 @@
+import { TDefaultParams, IShouldIgnore, TFlattenIgnore } from './common';
+export interface ISlsPipeOptions {
+    trackUrl: string;
+    /**
+     * 不知所谓的参数，但必需，说是保留字段，默认 `0.6.0`（文档中的版本号），请不要使用
+     */
+    apiVersion: string;
+    /**
+     * 应用初始化后，多少时间内对日志请求进行冷冻处理，以让行业务请求，提升业务性能
+     *
+     * 默认 5000ms
+     */
+    silentTime: number;
+    /**
+     * 调用方法到日志被真正发送的等待时间，这段时间内，若有新的日志进来，会被合并并重新计时
+     *
+     * 默认 200ms
+     */
+    waitTime: number;
+    /**
+     * 一次最多发送日志条数，若积累的日志数超过，将切成多个请求发送
+     *
+     * 默认 50
+     */
+    maxChunk: number;
+}
+export interface ICreateLoggerOptions extends Partial<ISlsPipeOptions> {
+    /**
+     * logstore 所在的 SLS project
+     */
+    project: string;
+    /**
+     * project 的外网访问域名，在 SLS 控制台 project 概览页可以找到，
+     * 如 `cn-hangzhou.log.aliyuncs.com`（仅跟 project 所在地域有关）
+     */
+    endpoint: string;
+    /**
+     * SLS project 下的 logstore，必须开通 Web Tracking 功能，日志记录的存储点
+     */
+    logstore: string;
+    /**
+     * 当希望同一个模块的日志使用统一的前缀，又不想每次调用的时候写，可以用这个
+     */
+    topicPrefix?: string;
+    /**
+     * 生产出的日志方法的整体采样率，可在调用时由方法参数覆盖，范围为 (0, 1]，默认 1
+     */
+    sampling?: number;
+    /**
+     * 默认参数，避免每次都要传，可以是静态数据或产生动态数据的方法，这些参数可以覆盖自动记录的参数，
+     * 但会被日志方法的第二个参数 `params` 中对应的字段覆盖
+     */
+    defaultParams?: TDefaultParams;
+    /**
+     * 上报之前进行判断是否继续，返回 false 以阻止上报
+     *
+     * 在某些场景下需要禁用日志上报功能，比如国外禁止将日志上报到国内的 logstore
+     */
+    shouldIgnore?: IShouldIgnore;
+}
+/**
+ * 生成 `createLogger` 方法的工厂方法的 options，用于制定工厂级别的参数的忽略方法
+ */
+export interface IGenerateCreateLoggerOptions {
+    defaultParams?: TDefaultParams;
+    shouldIgnore?: IShouldIgnore;
+}
+export interface ISlsFlattenOptions {
+    prefix?: string;
+    depth?: number;
+    ignore?: TFlattenIgnore;
+}
+/**
+ * SLS 日志方法 Options
+ */
+export interface ISlsLogOptions {
+    /**
+     * 覆盖 IFactoryOptions 的 topicPrefix 设置，仅针对当前日志
+     */
+    topicPrefix?: string;
+    /**
+     * 覆盖 IFactoryOptions 的 sampling 设置，仅针对当前日志
+     */
+    sampling?: number;
+    /**
+     * 有日志只需要在应用起来后记录一次，后续的将被丢弃
+     *
+     * - true 表示以该 topic 做判断，针对该 topic 只记录一次
+     * - 如果是字符串，则以「topic + 此字符串」做判断
+     */
+    once?: true | string;
+    /**
+     * 日志不是强需求，不能压过业务，要业务先行。网络请求一般在页面的一开始最密集，如果日志在这时上报会造成网络阻塞而产生性能问题。
+     *
+     * 办法是先积压着，等到时间到了，再把积压着的日志一起上报。
+     *
+     * 所以，为了提升性能，做了以下事情：
+     *
+     * 1. 应用起来后，有一定的静默时间，这段时间的日志会被积压，用于给应用的请求让路
+     * 2. 整体或单个日志的延时时间
+     * 3. 整体或单个日志的采样率
+     * 4. 有的日志只会发送一次
+     * 5. 日志发送前也有一个很短的等待时间，在这段时间内，如果有新的日志进来，也将被积压，并重新计时
+     * 6. 最后，积压的日志利用 POST 请求对日志进行合并发送
+     *
+     * 然而，总有例外，有的日志希望是即时的，比如需要拿它来算 PvUv，instant 就是为此而生。
+     * 注意：instant 会忽略延时，但不会忽略采样率
+     */
+    instant?: boolean;
+    /**
+     * 是否对 info 进行 flatten 操作
+     */
+    flatten?: boolean | string | ISlsFlattenOptions;
+    /**
+     * 为日志增加默认参数 `_GROUP`，可用于数据分析分组
+     */
+    group?: string;
+}
+/**
+ * SLS 快捷方法 Options
+ */
+export interface ISlsLogOptionsQuick extends Omit<ISlsLogOptions, 'group'> {
+}

package/dist/types/util/build-post-body.d.ts

@@ -0,0 +1,8 @@
+import type { ISlsLogPayload, ISlsPostBody } from '../types';
+/**
+ * 利用 PutWebTracking 发送日志，如果 `__logs__` 里含有 `__topic__` 则，外部的这个 `__topic__` 将被改为 `__topic__0`，
+ * 为了干净，在仅发送一条日志的时候，将 `__logs__` 里的 `__topic__` 往上提。
+ *
+ * 但是，POST 的时候 `__source__` 不会被默认填充成 IP，IP 在 `__tag__:__client_ip__`（GET 方式也有）
+ */
+export default function buildPostBody(payloads: ISlsLogPayload[]): ISlsPostBody;

package/dist/types/util/convert-error-to-plain.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Error 身上的 name、message、stack 等信息用 _forEach 遍历不到，故需要转成普通对象
+ */
+export default function convertErrorToPlain(err: Error): Record<string, unknown>;

package/dist/types/util/convert-log-info.d.ts

@@ -0,0 +1,8 @@
+import type { ISlsLogPayload } from '../types';
+/**
+ * 发送的 JSON 里边不可以有除了字符串以外的值，否则报错
+ *
+ * - code = PostBodyInvalid
+ * - message = Value in log is not string data type
+ */
+export default function convertLogInfo(info: ISlsLogPayload): Record<string, string>;

package/dist/types/util/create-sls-log-quick.d.ts

@@ -0,0 +1,2 @@
+import { ISlsLogFn, ISlsLogFnQuick } from '../types';
+export default function createSlsLogQuick(sls: ISlsLogFn, group: string): ISlsLogFnQuick;

package/dist/types/util/flatten-object.d.ts

@@ -0,0 +1,13 @@
+import type { ISlsFlattenOptions } from '../types';
+/**
+ * 有时候为了统计方便，需要把传入的对象展平，比如 error 对象，可能会展平成如下形状：
+ *
+ * ```
+ * {
+ *   "error.name": "..",
+ *   "error.message": "..",
+ *   "error.stack": ".."
+ * }
+ * ```
+ */
+export default function flattenObject<T extends object>(o: T, options: string | ISlsFlattenOptions): Record<string, unknown>;

package/dist/types/util/flatten-should-ignore.d.ts

@@ -0,0 +1,2 @@
+import type { ISlsFlattenOptions } from '../types';
+export default function flattenShouldIgnore(ignore: ISlsFlattenOptions['ignore'], path: string, key: string, value: unknown): boolean;

package/dist/types/util/get-log-once-key.d.ts

@@ -0,0 +1 @@
+export default function getLogOnceKey(topic: string, once?: true | string): string | undefined;

package/dist/types/util/get-silent-countdown.d.ts

@@ -0,0 +1 @@
+export default function getSilentCountdown(silentTime: number): number;

package/dist/types/util/index.d.ts

@@ -0,0 +1,9 @@
+export { default as getSilentCountdown } from './get-silent-countdown';
+export { default as getLogOnceKey } from './get-log-once-key';
+export { default as flattenObject } from './flatten-object';
+export { default as buildPostBody } from './build-post-body';
+export { default as convertErrorToPlain } from './convert-error-to-plain';
+export { default as resolveDefaultParams } from './resolve-default-params';
+export { default as createSlsLogQuick } from './create-sls-log-quick';
+export { default as mergeDefaultParams } from './merge-default-params';
+export { default as mergeShouldIgnore } from './merge-should-ignore';

package/dist/types/util/merge-default-params.d.ts

@@ -0,0 +1,5 @@
+import type { TDefaultParams } from '../types';
+/**
+ * 合并默认参数
+ */
+export default function mergeDefaultParams(factoryDefaultParams?: TDefaultParams, defaultParams?: TDefaultParams): TDefaultParams | undefined;

package/dist/types/util/merge-should-ignore.d.ts

@@ -0,0 +1,2 @@
+import type { IShouldIgnore } from '../types';
+export default function mergeShouldIgnore(factoryShouldIgnore?: IShouldIgnore, shouldIgnore?: IShouldIgnore): IShouldIgnore | undefined;

package/dist/types/util/resolve-default-params.d.ts

@@ -0,0 +1,2 @@
+import { TDefaultParams } from '../types';
+export default function resolveDefaultParams(defaultParams?: TDefaultParams): Record<string, unknown> | undefined;

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@kcuf/sls-logger-base",
+  "version": "0.0.1",
+  "description": "Aliyun SLS logger without transport implementation.",
+  "keywords": [],
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justnewbee/kcuf.git"
+  },
+  "homepage": "https://github.com/justnewbee/kcuf/tree/master/packages-fetcher/sls-logger-base",
+  "bugs": "https://github.com/justnewbee/kcuf/issues",
+  "author": {
+    "name": "Jianchun Wang",
+    "email": "justnewbee@gmail.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.25.6",
+    "@babel/core": "^7.25.2",
+    "@babel/plugin-transform-runtime": "^7.25.4",
+    "@babel/preset-env": "^7.25.4",
+    "@babel/preset-typescript": "^7.24.7",
+    "@types/lodash": "^4.17.7",
+    "@vitest/coverage-v8": "^2.1.1",
+    "fetch-mock": "^11.1.4",
+    "jsdom": "^25.0.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1",
+    "@kcuf/ts-config": "^0.0.1"
+  },
+  "peerDependencies": {
+    "@babel/runtime": "^7.24.8"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21"
+  },
+  "scripts": {
+    "build:clean": "rimraf dist",
+    "build:esm": "ESM=1 babel src -d dist/esm --extensions .ts,.tsx --source-maps",
+    "build:cjs": "ESM=0 babel src -d dist/cjs --extensions .ts,.tsx",
+    "build:types": "tsc -rootDir src --outDir dist/types --declaration --noEmit false --emitDeclarationOnly --isolatedModules false",
+    "build": "pnpm build:esm && pnpm build:cjs && pnpm build:types",
+    "watch": "pnpm build:esm -w",
+    "test": "vitest",
+    "test:cov": "vitest --coverage --coverage.include=src"
+  }
+}