@anjianshi/utils 3.0.0 → 3.0.2

package/env-service/prisma/extensions/soft-delete.js

@@ -0,0 +1,123 @@
+/**
+ * 扩展 Prisma 实现软删除
+ *
+ * 1. 有 deleteTime 字段的 model 支持软删除。
+ * 2. 执行 delete() 和 deleteMany() 时默认是进行软删除；可指定 soft 为 false 来彻底删除；执行软删除时可指定要额外更新的 data。
+ * 2. 查询时会忽略被软删除的记录；可指定 withDeleted 为 true 来包含它们。
+ * 4. 可通过 restore() 和 restoreMany() 恢复软删除的记录。
+ *
+ * 扩展实现方式参考：
+ * https://www.prisma.io/docs/orm/prisma-client/client-extensions/type-utilities#add-a-custom-property-to-a-method
+ * https://www.npmjs.com/package/@prisma/extension-accelerate?activeTab=code  =>  @prisma/extension-accelerate/dist/esm/extension.js
+ *
+ * 此扩展修改了 Prisma 的原生方法。
+ * 为保证其他扩展也应用到修改过的这些方法，此扩展应尽可能放在最前面。
+ */
+import { Prisma } from '@prisma/client/extension';
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+function getModel(that) {
+    const context = Prisma.getExtensionContext(that);
+    // 1. 此扩展修改了 Prisma 原生的方法，所以要通过 context.$parent[context.$name] 获取上一层的 model，不然会自己调用自己导致死循环。
+    // 2. 如果此扩展后面还应用了其他扩展，那么仅仅一层 $parent 取得的 model 还是这个扩展修改过的版本而不是原生的。
+    //    此时需要递归向上，直到取得未经此扩展修改过的 model。不然此扩展的业务逻辑会被重复执行，
+    //    而因为第一次执行时已经把定制参数消解掉了，第二次执行时会误以为没有传入定制参数，最终导致定制参数失效。
+    let model = context;
+    do {
+        model = model.$parent[context.$name];
+    } while ('withSoftDeleteExtension' in model);
+    const supportSoftDelete = 'deleteTime' in model.fields;
+    return { model, supportSoftDelete };
+}
+function query(that, inputArgs, method) {
+    const { model, supportSoftDelete } = getModel(that);
+    // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+    const { withDeleted = false, ...args } = inputArgs;
+    return model[method]({
+        ...args,
+        where: !supportSoftDelete || withDeleted ? args.where : { ...args.where, deleteTime: null },
+    });
+}
+export const softDelete = Prisma.defineExtension({
+    name: 'softDeleted',
+    model: {
+        $allModels: {
+            withSoftDeleteExtension: true,
+            // -----------------------------
+            // 操作
+            // -----------------------------
+            delete(rawArgs) {
+                const { model, supportSoftDelete } = getModel(this);
+                const { soft = true, data, ...args } = rawArgs;
+                if (supportSoftDelete && soft) {
+                    return model.update({
+                        ...args, // .delete() 的参数 .update() 也都支持
+                        data: { ...(data ?? {}), deleteTime: new Date() },
+                    }); // .update() 的返回值和 .delete() 一样
+                }
+                else {
+                    return model.delete(args);
+                }
+            },
+            deleteMany(rawArgs) {
+                const { model, supportSoftDelete } = getModel(this);
+                const { soft = true, data, ...args } = rawArgs;
+                if (supportSoftDelete && soft) {
+                    return model.updateMany({
+                        ...args, // .deleteMany() 的参数 .updateMany() 也都支持
+                        data: { ...(data ?? {}), deleteTime: new Date() },
+                    }); // .updateMany() 的返回值和 .deleteMany() 一样
+                }
+                else {
+                    return model.deleteMany(args);
+                }
+            },
+            restore(rawArgs) {
+                const { data, ...args } = rawArgs;
+                const { model, supportSoftDelete } = getModel(this);
+                if (!supportSoftDelete)
+                    throw new Error('当前模型不支持软删除，不能执行恢复');
+                return model.update({
+                    ...args,
+                    data: { ...(data ?? {}), deleteTime: null },
+                });
+            },
+            restoreMany(rawArgs) {
+                const { data, ...args } = rawArgs;
+                const { model, supportSoftDelete } = getModel(this);
+                if (!supportSoftDelete)
+                    throw new Error('当前模型不支持软删除，不能执行恢复');
+                return model.updateMany({
+                    ...args,
+                    data: { ...(data ?? {}), deleteTime: new Date() },
+                });
+            },
+            // -----------------------------
+            // 查询
+            // -----------------------------
+            aggregate(inputArgs) {
+                return query(this, inputArgs, 'aggregate');
+            },
+            count(inputArgs) {
+                return query(this, inputArgs, 'count');
+            },
+            findFirst(inputArgs) {
+                return query(this, inputArgs, 'findFirst');
+            },
+            findFirstOrThrow(inputArgs) {
+                return query(this, inputArgs, 'findFirstOrThrow');
+            },
+            findMany(inputArgs) {
+                return query(this, inputArgs, 'findMany');
+            },
+            findUnique(inputArgs) {
+                return query(this, inputArgs, 'findUnique');
+            },
+            findUniqueOrThrow(inputArgs) {
+                return query(this, inputArgs, 'findUniqueOrThrow');
+            },
+            groupBy(inputArgs) {
+                return query(this, inputArgs, 'groupBy');
+            },
+        },
+    },
+});

package/env-service/prisma/extensions/with-transaction.d.ts

@@ -0,0 +1,9 @@
+import { type ITXClientDenyList } from '@prisma/client/runtime/library.js';
+import type { Result, Failed } from '../../../index.js';
+export declare const withTransaction: (client: any) => import("@prisma/client/extension").PrismaClientExtends<import("@prisma/client/runtime/library").InternalArgs<{}, {}, {}, {
+    $withTransaction: typeof $withTransaction;
+}>>;
+export type GetPrismaClientInTransaction<PrismaClient> = Omit<PrismaClient, ITXClientDenyList>;
+export type WithTransactionMethod = typeof $withTransaction;
+declare function $withTransaction<That extends object, R extends Result<unknown, unknown>>(this: That, callback: (dbInTransaction: GetPrismaClientInTransaction<That>) => Promise<R>): Promise<Failed<any> | R>;
+export {};

package/env-service/prisma/extensions/with-transaction.js

@@ -0,0 +1,54 @@
+/**
+ * 在事务中执行回调。与 $transaction 有几点不同：
+ * 1. 回调必须返回 Result 值
+ * 2. 回调返回 Failed 值或抛出异常都会触发回滚。
+ *    如果是返回 Failed，会作为此方法的返回值；如果是抛出异常，则异常会继续向上传递，直到被捕获或触发请求失败。
+ * 3. 如果已经处于事务中，会沿用上层事务，且回调返回 Failed 或抛出异常会触发上层事务的回滚。
+ *
+ * const result: Result = await db.$withTransaction(
+ *   async (dbInTransaction) => {
+ *     // do something
+ *     return success()
+ *   }
+ * )
+ */
+import { Prisma } from '@prisma/client/extension.js';
+export const withTransaction = Prisma.defineExtension({
+    name: 'withTransaction',
+    client: {
+        $withTransaction,
+    },
+});
+class FailedInTransaction extends Error {
+    failed;
+    constructor(failed) {
+        super(failed.message);
+        this.failed = failed;
+    }
+}
+// 注意：此函数的返回值为 `R | Failed<any>`，例如实际可能为 `Result<xxx, xxx> | Failed<any>`，这是有意为之的，`Failed<any>` 并不多余。
+// 因为有时 callback() 只会返回 success 结果，此时 R=Success<xxx>，但是 $withTransaction 整体的返回值仍有可能有 Failed<any>，所以不能用 R 作为整体返回值。
+async function $withTransaction(callback) {
+    const executeCallback = async (dbInTransaction) => {
+        const result = await callback(dbInTransaction);
+        if (result.success)
+            return result;
+        else
+            throw new FailedInTransaction(result);
+    };
+    if ('$transaction' in this && this.$transaction) {
+        // 如果当前不在事务中，开启新事务并执行回调
+        try {
+            return await this.$transaction(async (dbInTransaction) => executeCallback(dbInTransaction));
+        }
+        catch (e) {
+            if (e instanceof FailedInTransaction)
+                return e.failed;
+            throw e;
+        }
+    }
+    else {
+        // 已经在事务中，直接执行回调（如果有异常，上层开启事务的代码会捕获）
+        return executeCallback(this);
+    }
+}

package/env-service/prisma/index.d.ts

@@ -0,0 +1,6 @@
+export * from './extensions/exist.js';
+export * from './extensions/find-and-count.js';
+export * from './extensions/soft-delete.js';
+export * from './extensions/with-transaction.js';
+export * from './transaction-contexted.js';
+export * from './adapt-logging.js';

package/env-service/prisma/index.js

@@ -0,0 +1,6 @@
+export * from './extensions/exist.js';
+export * from './extensions/find-and-count.js';
+export * from './extensions/soft-delete.js';
+export * from './extensions/with-transaction.js';
+export * from './transaction-contexted.js';
+export * from './adapt-logging.js';

package/env-service/prisma/transaction-contexted.d.ts

@@ -0,0 +1,11 @@
+import type { WithTransactionMethod } from './extensions/with-transaction.js';
+/**
+ * 返回一个可以在事务内和事务外通用的 PrismaClient 代理对象。
+ * 当前在事务内时，调用它是调用事务内的 client；当前不在事务内时，调用它是调用全局 client。
+ * 这样当一个事务涉及多个函数调用时，就不用把事务内 client 传递来传递去了。
+ * 注意：应给每个线性流程（例如一个请求）单独生成一个此对象，不能作为全局对象使用，不然可能出现事务冲突。
+ */
+export declare function getTransactionContextedPrismaClient<AppPrismaClient extends {
+    $transaction: (...args: any[]) => Promise<unknown>;
+    $withTransaction: WithTransactionMethod;
+}>(prisma: AppPrismaClient): AppPrismaClient;

package/env-service/prisma/transaction-contexted.js

@@ -0,0 +1,52 @@
+/**
+ * 返回一个可以在事务内和事务外通用的 PrismaClient 代理对象。
+ * 当前在事务内时，调用它是调用事务内的 client；当前不在事务内时，调用它是调用全局 client。
+ * 这样当一个事务涉及多个函数调用时，就不用把事务内 client 传递来传递去了。
+ * 注意：应给每个线性流程（例如一个请求）单独生成一个此对象，不能作为全局对象使用，不然可能出现事务冲突。
+ */
+export function getTransactionContextedPrismaClient(prisma) {
+    let client = prisma;
+    async function callCallbackInTransaction(callback, clientInTransaction) {
+        const prevClient = client;
+        const currentClient = clientInTransaction;
+        client = currentClient;
+        function restoreClient() {
+            if (client !== currentClient)
+                throw new Error('事务冲突，必须等一个事务结束后再开启另一个事务');
+            client = prevClient;
+        }
+        try {
+            const res = await callback(client);
+            restoreClient();
+            return res;
+        }
+        catch (e) {
+            restoreClient();
+            throw e;
+        }
+    }
+    async function $transaction(arg, ...restArgs) {
+        if (typeof arg === 'function') {
+            const wrappedCallback = callCallbackInTransaction.bind(null, arg);
+            return client.$transaction(wrappedCallback, ...restArgs);
+        }
+        else {
+            return client.$transaction(arg, ...restArgs);
+        }
+    }
+    async function $withTransaction(callback) {
+        return client.$withTransaction(async (clientInTransaction) => callCallbackInTransaction(callback, clientInTransaction));
+    }
+    return new Proxy({}, {
+        has(_, prop) {
+            return prop in client;
+        },
+        get(_, prop) {
+            if (prop === '$transaction')
+                return $transaction;
+            if (prop === '$withTransaction')
+                return $withTransaction;
+            return client[prop];
+        },
+    });
+}

package/env-service/redis-cache.d.ts

@@ -0,0 +1,39 @@
+import { type RedisClientType } from 'redis';
+import { type Logger } from '../logging/index.js';
+export declare function initRedisLogging(redis: RedisClientType, logger?: Logger): void;
+export interface CacheOptions {
+    logger: Logger;
+    /** 数据有效期，单位秒。默认为 10 分钟。小于等于 0 代表不设有效期 */
+    expires: number;
+    /** 读取时是否自动刷新有效期，仅设置了 expire 时有效，默认为 true */
+    refreshOnRead: boolean;
+    /** 若为 true，读取数据后会立即将其删除，默认为 false */
+    oneTime: boolean;
+}
+/**
+ * 维护缓存数据
+ * 1. 每个 Cache 实例只维护一个主题的数据，且需明确定义数据类型，这样设计可明确对每一项缓存的使用、避免混乱。
+ * 2. 值在存储时会 JSON 化，读取时再进行 JSON 解析（支持 JSON 化 Date 对象）。
+ */
+export declare class Cache<T> {
+    readonly redis: RedisClientType;
+    readonly topic: string;
+    readonly options: CacheOptions;
+    constructor(redis: RedisClientType, topic: string, options?: Partial<CacheOptions>);
+    get logger(): Logger;
+    protected jsonStringify(value: T): string;
+    protected jsonParse(redisValue: string): T;
+    protected getRedisKey(identity: string): string;
+    /** 读取一项内容 */
+    get(identity: string, defaults: T): Promise<T>;
+    get(identity?: string): Promise<T | undefined>;
+    /** 写入/更新一项内容 */
+    set(value: T): Promise<void>;
+    set(identity: string, value: T): Promise<void>;
+    /** 移除一项内容 */
+    delete(identity?: string | string[]): Promise<number>;
+    /** 刷新一项内容的过期时间 */
+    refresh(identity?: string): Promise<number | false>;
+    /** 确认一项内容是否存在  */
+    exists(identity?: string): Promise<boolean>;
+}

package/env-service/redis-cache.js

@@ -0,0 +1,116 @@
+import { logger as rootLogger } from '../logging/index.js';
+export function initRedisLogging(redis, logger) {
+    logger ??= rootLogger.getChild('redis');
+    redis.on('connect', () => logger.info('connecting'));
+    redis.on('ready', () => logger.info('connected'));
+    redis.on('end', () => logger.info('connection closed'));
+    redis.on('reconnecting', () => logger.info('reconnecting'));
+    redis.on('error', error => logger.error(error));
+}
+/**
+ * 维护缓存数据
+ * 1. 每个 Cache 实例只维护一个主题的数据，且需明确定义数据类型，这样设计可明确对每一项缓存的使用、避免混乱。
+ * 2. 值在存储时会 JSON 化，读取时再进行 JSON 解析（支持 JSON 化 Date 对象）。
+ */
+export class Cache {
+    redis;
+    topic;
+    options;
+    constructor(redis, topic, options) {
+        this.redis = redis;
+        this.topic = topic;
+        this.options = {
+            logger: rootLogger.getChild('cache'),
+            expires: 600,
+            refreshOnRead: true,
+            oneTime: false,
+            ...(options ?? {}),
+        };
+    }
+    get logger() {
+        return this.options.logger;
+    }
+    // 经过定制的 JSON 序列化和解析方法
+    jsonStringify(value) {
+        // 参考：https://stackoverflow.com/a/54037861/2815178
+        function replacer(key, value) {
+            // value 是经过预处理过的值，对于 Date 对象，此时已经是 string，需要通过 this[key] 才能拿到 Date 值。
+            const rawValue = this[key];
+            if (rawValue instanceof Date)
+                return { __json_type: 'date', value: rawValue.toISOString() };
+            return value;
+        }
+        return JSON.stringify(value, replacer);
+    }
+    jsonParse(redisValue) {
+        function reviver(key, value) {
+            if (typeof value === 'object' && value !== null) {
+                const obj = value;
+                if (obj.__json_type === 'date')
+                    return new Date(obj.value);
+            }
+            return value;
+        }
+        return JSON.parse(redisValue, reviver);
+    }
+    getRedisKey(identity) {
+        return `${this.topic}${identity ? ':' + identity : ''}`;
+    }
+    async get(identity = '', defaults) {
+        const redisKey = this.getRedisKey(identity);
+        const redisValue = await this.redis.get(redisKey);
+        this.logger.debug('get', redisKey, redisValue);
+        if (redisValue === null)
+            return defaults;
+        if (this.options.refreshOnRead)
+            void this.refresh(identity);
+        try {
+            const value = this.jsonParse(redisValue);
+            if (this.options.oneTime)
+                await this.delete(identity);
+            return value;
+        }
+        catch (error) {
+            this.logger.error(`解析 cache 数据失败，key=${redisKey}，value=${redisValue}`, error);
+            void this.delete(identity);
+            return defaults;
+        }
+    }
+    async set(identity, value) {
+        if (value === undefined) {
+            value = identity;
+            identity = '';
+        }
+        else {
+            identity = identity;
+        }
+        const redisKey = this.getRedisKey(identity);
+        let redisValue;
+        try {
+            redisValue = this.jsonStringify(value);
+        }
+        catch (error) {
+            this.logger.error(`格式化 cache 数据失败，key=${redisKey}`, value, error);
+            throw error;
+        }
+        this.logger.debug('set', redisKey, redisValue);
+        await this.redis.set(redisKey, redisValue, { EX: this.options.expires });
+    }
+    /** 移除一项内容 */
+    async delete(identity = '') {
+        const identities = Array.isArray(identity) ? identity : [identity];
+        this.logger.debug('delete', identities);
+        return this.redis.del(identities.map(identity => this.getRedisKey(identity)));
+    }
+    /** 刷新一项内容的过期时间 */
+    async refresh(identity = '') {
+        if (this.options.expires >= 0)
+            return this.redis.expire(this.getRedisKey(identity), this.options.expires);
+        else
+            return false;
+    }
+    /** 确认一项内容是否存在  */
+    async exists(identity = '') {
+        return (await this.redis.exists(this.getRedisKey(identity))) === 1;
+    }
+}

package/env-service/tasks.d.ts

@@ -0,0 +1,12 @@
+import { type Logger } from '../logging/index.js';
+/** 返回 false 可结束任务 */
+export type TaskExecutor<Context> = (context: Context, logger: Logger) => Promise<void> | Promise<undefined | boolean>;
+/**
+ * 执行定期任务
+ */
+export declare abstract class TaskManager<Context> {
+    protected baseLogger: Logger;
+    constructor(baseLogger?: Logger);
+    abstract getContext(taskName: string): Context;
+    run(name: string, interval: number, executor: TaskExecutor<Context>): Promise<void>;
+}

package/env-service/tasks.js

@@ -0,0 +1,37 @@
+import { sleep } from '../lang/async.js';
+import { logger as rootLogger } from '../logging/index.js';
+/**
+ * 执行定期任务
+ */
+export class TaskManager {
+    baseLogger;
+    constructor(baseLogger = rootLogger.getChild('task')) {
+        this.baseLogger = baseLogger;
+    }
+    async run(name, interval, executor) {
+        await sleep(1000);
+        const logger = this.baseLogger.getChild(name);
+        let nextId = 1;
+        while (true) {
+            const id = nextId++;
+            if (id >= Number.MAX_SAFE_INTEGER)
+                nextId = 1;
+            const start = Date.now();
+            logger.info(`#${id} 任务开始`);
+            try {
+                const context = this.getContext(name);
+                const result = await executor(context, logger);
+                const cost = (Date.now() - start) / 1000;
+                logger.info(`#${id} 任务完成，耗时 ${cost}s`);
+                if (result === false) {
+                    logger.info('任务结束');
+                    break;
+                }
+            }
+            catch (err) {
+                logger.error(`#${id} 任务失败`, err);
+            }
+            await sleep(interval);
+        }
+    }
+}

package/index.d.ts

@@ -0,0 +1,4 @@
+export * from './lang/index.js';
+export * from './url.js';
+export * from './safe-request.js';
+export * from './logging/index.js';

package/index.js

@@ -0,0 +1,4 @@
+export * from './lang/index.js';
+export * from './url.js';
+export * from './safe-request.js';
+export * from './logging/index.js';

package/init-dayjs.d.ts

@@ -0,0 +1,2 @@
+import 'dayjs/locale/zh-cn.js';
+export declare function initDayJs(): void;

package/init-dayjs.js

@@ -0,0 +1,7 @@
+import dayjs from 'dayjs';
+import objectSupport from 'dayjs/plugin/objectSupport.js';
+import 'dayjs/locale/zh-cn.js';
+export function initDayJs() {
+    dayjs.extend(objectSupport);
+    dayjs.locale('zh-cn');
+}

package/lang/async.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 异步行为相关函数
+ */
+/**
+ * 返回一个指定毫秒后 resolve 的 Promise
+ * 若指定了 resolveValue，则 Promise 最终会解析出此值
+ */
+declare function sleep(ms: number): Promise<undefined>;
+declare function sleep<T>(ms: number, resolveValue: T): Promise<T>;
+export { sleep };
+/**
+ * 给 Promise 增加时限。
+ * - 若 silent 为 false，超时时 reject 一个 TimeoutError
+ * - 若 silent 为 true，则超时后，promise 永远不会 resolve 或 reject
+ */
+export declare function timeout<T>(promise: Promise<T>, timeoutMS: number, silent?: boolean): Promise<T>;
+export declare class TimeoutError extends Error {
+    isTimeout: boolean;
+}

package/lang/async.js

@@ -0,0 +1,34 @@
+/**
+ * 异步行为相关函数
+ */
+async function sleep(ms, resolveValue) {
+    return new Promise(resolve => {
+        setTimeout(() => resolve(resolveValue), ms);
+    });
+}
+export { sleep };
+/**
+ * 给 Promise 增加时限。
+ * - 若 silent 为 false，超时时 reject 一个 TimeoutError
+ * - 若 silent 为 true，则超时后，promise 永远不会 resolve 或 reject
+ */
+export async function timeout(promise, timeoutMS, silent = false) {
+    return new Promise((resolve, reject) => {
+        let isTimeout = false;
+        setTimeout(() => {
+            isTimeout = true;
+            if (!silent)
+                reject(new TimeoutError('timeout'));
+        }, timeoutMS);
+        promise.then(result => {
+            if (!isTimeout)
+                resolve(result);
+        }, (error) => {
+            if (!isTimeout)
+                reject(error);
+        });
+    });
+}
+export class TimeoutError extends Error {
+    isTimeout = true;
+}

package/lang/color.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 计算颜色数值
+ */
+/**
+ * hex 颜色字符串转换为 rgba 数值
+ * 例如 '#22334455' => [34,51,68,0.33]
+ *
+ * hex 字符串支持以下格式：
+ * - 带/不带开头的 #
+ * - #RGB
+ * - #RGBA
+ * - #RRGGBB
+ * - #RRGGBBAA
+ */
+export declare function hex2rgba(rawHex: string): readonly [number, number, number, number];
+/**
+ * 把 rgba 数组转换为 hex 颜色字符串
+ * 如果 alpha 部分为 1，会将其省略
+ * [34,51,68,0.33] => '#22334455'
+ */
+export declare function rgba2hex(rgba: [number, number, number, number]): string;
+/**
+ * rgb 转成 hsl 值（以便计算亮度）
+ * https://www.rapidtables.com/convert/color/rgb-to-hsl.html
+ */
+export declare function rgb2hsl([r, g, b]: [number, number, number]): readonly [number, number, number];
+/**
+ * hsl 转成 rgb
+ * https://www.rapidtables.com/convert/color/hsl-to-rgb.html
+ */
+export declare function hsl2rgb([h, s, l]: [number, number, number]): readonly [number, number, number];
+/**
+ * 调整颜色深浅
+ * lightness('#111', 0.2)  => lighten(20%)
+ * lightness('#111', -0.5)  => darken(50%)
+ */
+export declare function lightness(hex: string, ratio: number): string;