@anjianshi/utils 1.2.7 → 1.3.0

package/env-node/env-reader.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 读取 .env 文件，并获取格式化后的数据
+ * 注意：依赖 dotenv 包
+ */
+export declare class EnvReader {
+    readonly envFile: string;
+    envsFromFile: Record<string, string>;
+    constructor(envFile: string);
+    get(key: string, defaults: string): string;
+    get(key: string, defaults: number): number;
+    get(key: string, defaults: boolean): boolean;
+}

package/env-node/env-reader.js

@@ -0,0 +1,31 @@
+import * as dotenv from 'dotenv';
+/**
+ * 读取 .env 文件，并获取格式化后的数据
+ * 注意：依赖 dotenv 包
+ */
+export class EnvReader {
+    envFile;
+    envsFromFile = {};
+    constructor(envFile) {
+        this.envFile = envFile;
+        dotenv.config({
+            path: this.envFile,
+            processEnv: this.envsFromFile, // 把从 .env 文件读到的内容写入到此实例的属性，而不是 process.env
+        });
+    }
+    get(key, defaults) {
+        const value = this.envsFromFile[key] ?? process.env[key];
+        if (value === undefined)
+            return defaults;
+        if (typeof defaults === 'number') {
+            const numValue = parseInt(value, 10);
+            return isFinite(numValue) ? numValue : defaults;
+        }
+        else if (typeof defaults === 'boolean') {
+            return ['1', 'true'].includes(value.toLowerCase().trim());
+        }
+        else {
+            return value;
+        }
+    }
+}

package/env-node/{logging.d.ts → logging/handlers.d.ts}

@@ -1,5 +1,4 @@
-import { type Logger, type LogInfo, LogHandler } from '../logging/index.js';
-export * from '../logging/index.js';
+import { type LogInfo, LogHandler } from '../../logging/index.js';
 /**
  * 向 console 输出日志
  */
@@ -57,7 +56,3 @@ export declare class FileHandler extends LogHandler {
     protected initLogDir(): void;
     protected write(content: string): void;
 }
-/**
- * 预设的初始化行为
- */
-export declare function initLogger(logger?: Logger): void;

package/env-node/{logging.js → logging/handlers.js}

@@ -1,14 +1,9 @@
-/**
- * 针对 Node.js 环境定制 logging
- * 注意：使用此模块需要 chalk 依赖
- */
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
 import dayjs from 'dayjs';
-import { logger as defaultLogger, LogLevel, LogHandler, formatters, } from '../logging/index.js';
-export * from '../logging/index.js';
+import { LogLevel, LogHandler, formatters } from '../../logging/index.js';
 /**
  * 向 console 输出日志
  */
@@ -151,9 +146,3 @@ export class FileHandler extends LogHandler {
         });
     }
 }
-/**
- * 预设的初始化行为
- */
-export function initLogger(logger = defaultLogger) {
-    logger.addHandler(new ConsoleHandler());
-}

package/env-node/logging/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 针对 Node.js 环境定制 logging
+ * 注意：使用此模块需要 chalk 依赖
+ */
+import { type Logger } from '../../logging/index.js';
+export * from './handlers.js';
+export * from '../../logging/index.js';
+/**
+ * 预设的初始化行为
+ */
+export declare function initLogger(logger?: Logger): void;

package/env-node/logging/index.js

@@ -0,0 +1,14 @@
+/**
+ * 针对 Node.js 环境定制 logging
+ * 注意：使用此模块需要 chalk 依赖
+ */
+import { logger as defaultLogger } from '../../logging/index.js';
+import { ConsoleHandler } from './handlers.js';
+export * from './handlers.js';
+export * from '../../logging/index.js';
+/**
+ * 预设的初始化行为
+ */
+export function initLogger(logger = defaultLogger) {
+    logger.addHandler(new ConsoleHandler());
+}

package/env-node/typeorm/adapt-logging.d.ts

@@ -0,0 +1,11 @@
+import { AbstractLogger, type LogLevel as TypeORMLogLevel, type LogMessage, type LoggerOptions } from 'typeorm';
+import { type Logger as UtilsLogger } from '../logging/index.js';
+/**
+ * 把 TypeORM 的日志导入到 js-utils 的 logger 中
+ * 用法参考 https://typeorm.io/logging
+ */
+export declare class AdaptedTypeORMLogger extends AbstractLogger {
+    readonly utilsLogger: UtilsLogger;
+    constructor(utilsLogger: UtilsLogger, options?: LoggerOptions);
+    protected writeLog(typeORMLevel: TypeORMLogLevel, logMessage: LogMessage | LogMessage[]): void;
+}

package/env-node/typeorm/adapt-logging.js

@@ -0,0 +1,42 @@
+import { AbstractLogger, } from 'typeorm';
+/**
+ * 把 TypeORM 的日志导入到 js-utils 的 logger 中
+ * 用法参考 https://typeorm.io/logging
+ */
+export class AdaptedTypeORMLogger extends AbstractLogger {
+    utilsLogger;
+    constructor(utilsLogger, options) {
+        super(options);
+        this.utilsLogger = utilsLogger;
+    }
+    writeLog(typeORMLevel, logMessage) {
+        const messages = this.prepareLogMessages(logMessage, {
+            highlightSql: true,
+        });
+        for (const message of messages) {
+            const args = message.prefix ?? '' ? [message.prefix, message.message] : [message.message];
+            switch (message.type ?? typeORMLevel) {
+                case 'log':
+                case 'schema':
+                case 'schema-build':
+                case 'migration':
+                    this.utilsLogger.debug(...args);
+                    break;
+                case 'info':
+                case 'query':
+                    this.utilsLogger.info(...args);
+                    break;
+                case 'warn':
+                case 'query-slow':
+                    this.utilsLogger.warn(...args);
+                    break;
+                case 'error':
+                case 'query-error':
+                    this.utilsLogger.error(...args);
+                    break;
+                default:
+                    this.utilsLogger.debug(...args);
+            }
+        }
+    }
+}

package/env-node/typeorm/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * TypeORM 相关工具函数
+ */
+import { type FindOptionsWhere, type BaseEntity } from 'typeorm';
+import { type ExcluceMethods } from '../../lang/index.js';
+export * from './adapt-logging.js';
+/**
+ * 返回 Entity 对应的纯数据类型
+ */
+export type DataOnly<T extends BaseEntity> = Omit<ExcluceMethods<T>, 'hasId'>;
+/**
+ * 转义字符串以安全地进行 SQL LIKE 匹配
+ */
+export declare function escapeLikeString(raw: string, escapeChar?: string): string;
+/**
+ * 返回 instances 里没有出现的 id
+ */
+export declare function getNotExistIds<T extends {
+    id: string;
+}>(instances: T[], ids: string[]): string[];
+/**
+ * TypeORM 的 find({ where: {} }) 里不支持 AND 和 OR 并列使用
+ * 例如：is_disabled IS NULL AND (name LIKE '%ab%' OR nickname LIKE '%ab%')
+ * 只能蹩脚地写成 `where: [{ name: LIKE('xx'), is_disabled: xx }, { nickname: LIKE('xx'), is_disabled: xx }]`
+ *
+ * 此函数简化了这一转换步骤，使得可以逻辑直观地并列书写 AND 和 OR。
+ * 在 `where: {}` 里，`or_` 开头且值是数组的项被组织为一个 OR，其 key 会被忽略，内容转换为上面的形式。
+ */
+declare function smartWhere<Entity>(where: FindOptionsWhere<Entity>): FindOptionsWhere<Entity>;
+declare function smartWhere<Entity>(where: FindOptionsWhere<Entity>[]): FindOptionsWhere<Entity>[];
+export { smartWhere };

package/env-node/typeorm/index.js

@@ -0,0 +1,39 @@
+export * from './adapt-logging.js';
+/**
+ * 转义字符串以安全地进行 SQL LIKE 匹配
+ */
+export function escapeLikeString(raw, escapeChar = '\\') {
+    return raw.replace(/[\\%_]/g, match => escapeChar + match);
+}
+/**
+ * 返回 instances 里没有出现的 id
+ */
+export function getNotExistIds(instances, ids) {
+    return ids.filter(id => !instances.find(inst => inst.id === id));
+}
+function smartWhere(where) {
+    if (Array.isArray(where))
+        return where.map(item => smartWhere(item));
+    const orPrefix = 'or_';
+    const orContent = {};
+    const andContent = {};
+    for (const [key, value] of Object.entries(where)) {
+        if (value === undefined)
+            continue;
+        if (key.startsWith(orPrefix) && Array.isArray(value)) {
+            orContent[key] = value;
+        }
+        else {
+            ;
+            andContent[key] = value;
+        }
+    }
+    const nextWhere = { ...where };
+    const currentOr = Object.entries(nextWhere).find(([key, value]) => key.startsWith(orPrefix) && Array.isArray(value));
+    if (currentOr === undefined)
+        return nextWhere;
+    delete nextWhere[currentOr[0]];
+    const result = currentOr[1].map(subWhere => ({ ...subWhere, ...smartWhere(nextWhere) }));
+    return result;
+}
+export { smartWhere };

package/lang/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types.js';
+export * from './may-success.js';
 export * from './string.js';
 export * from './object.js';
 export * from './time.js';

package/lang/index.js

@@ -1,4 +1,5 @@
 export * from './types.js';
+export * from './may-success.js';
 export * from './string.js';
 export * from './object.js';
 export * from './time.js';

package/lang/may-success.d.ts

@@ -0,0 +1,40 @@
+/**
+ * MaySuccess：代表一种“可能失败”的操作结果，可以作为函数返回值，也可以作为接口响应值。
+ * 它的灵感来自 Scala 的 Option 类型。
+ *
+ * 原本，在 JavaScript 里一个可能失败的操作有两种表示失败的方式：
+ * 1. 返回空值，如 null、0、''
+ * 2. 抛出异常
+ * 返回空值的方式无法附带失败信息；而抛出异常会导致层层嵌套的 try catch 语句，且其实性能不好。
+ *
+ * MaySuccess 就是为了解决这两个痛点：
+ * 1. 它的 Failed 类型可以携带失败信息。
+ * 2. 无需 try catch，只需简单的 result.success 判断
+ */
+/** 类型定义 */
+export interface Success<T = void> {
+    success: true;
+    data: T;
+}
+export type Failed<T = void> = {
+    success: false;
+    message: string;
+    code?: string | number;
+    data: T;
+};
+export type MaySuccess<T = void, FT = void> = Success<T> | Failed<FT>;
+/** 生成 Success 数据 */
+declare function success(): Success;
+declare function success<T>(data: T): Success<T>;
+export { success };
+/** 生成 Failed 数据 */
+declare function failed(message: string, code?: string | number): Failed;
+declare function failed<T>(message: string, code: string | number | undefined, data: T): Failed<T>;
+export { failed };
+/**
+ * 若传入值为 success，格式化其 data；否则原样返回错误
+ * 支持传入会返回 MaySuccess 的 Promise
+ */
+declare function formatSuccess<T1, T2, FT = void>(value: MaySuccess<T1, FT>, formatter: (value: T1) => T2): MaySuccess<T2, FT>;
+declare function formatSuccess<T1, T2, FT = void>(value: Promise<MaySuccess<T1, FT>>, formatter: (value: T1) => T2): Promise<MaySuccess<T2, FT>>;
+export { formatSuccess };

package/lang/may-success.js

@@ -0,0 +1,27 @@
+/**
+ * MaySuccess：代表一种“可能失败”的操作结果，可以作为函数返回值，也可以作为接口响应值。
+ * 它的灵感来自 Scala 的 Option 类型。
+ *
+ * 原本，在 JavaScript 里一个可能失败的操作有两种表示失败的方式：
+ * 1. 返回空值，如 null、0、''
+ * 2. 抛出异常
+ * 返回空值的方式无法附带失败信息；而抛出异常会导致层层嵌套的 try catch 语句，且其实性能不好。
+ *
+ * MaySuccess 就是为了解决这两个痛点：
+ * 1. 它的 Failed 类型可以携带失败信息。
+ * 2. 无需 try catch，只需简单的 result.success 判断
+ */
+function success(data) {
+    return { success: true, data };
+}
+export { success };
+function failed(message, code, data) {
+    return { success: false, message, code, data: data };
+}
+export { failed };
+function formatSuccess(value, formatter) {
+    if ('then' in value)
+        return value.then(finalValue => formatSuccess(finalValue, formatter));
+    return value.success ? success(formatter(value.data)) : value;
+}
+export { formatSuccess };

package/lang/types.d.ts

@@ -12,21 +12,13 @@
  * https://github.com/microsoft/TypeScript/issues/16656
  */
 export declare function tuple<T extends unknown[]>(...elements: T): T;
-/**
- * 将一个对象中的指定 key 设为必须的
- */
+/** 将一个对象中的指定 key 设为必须的 */
 export type RequiredFields<T, K extends keyof T> = Omit<T, K> & Pick<Required<T>, K>;
-/**
- * 将一个对象中的指定 key 设为非必须的
- */
+/** 将一个对象中的指定 key 设为非必须的 */
 export type OptionalFields<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-/**
- * 用 ReplaceT 中的字段定义代替 T 中的
- */
+/** 用 ReplaceT 中的字段定义代替 T 中的 */
 export type ReplaceFields<T, ReplaceT> = Omit<T, keyof ReplaceT> & ReplaceT;
-/**
- * 获取一个对象所有 value 的集合
- */
+/** 获取一个对象所有 value 的集合 */
 export type ValueOf<T> = T extends {
     [_ in keyof T]: infer U;
 } ? U : never;
@@ -42,40 +34,19 @@ export type ValueOf<T> = T extends {
 export type KnownKeys<T> = ValueOf<{
     [K in keyof T]: string extends K ? never : number extends K ? never : K;
 }>;
-/**
- * 排除对象中指定类型的项目
- */
+/** 排除对象中指定类型的项目 */
 export type ExcludePropertiesOfType<T, ExcludeValueT> = Pick<T, {
     [K in keyof T]: T[K] extends ExcludeValueT ? never : K;
 }[keyof T]>;
 /**
- * 排除对象的方法（仅保留属性）
+ * 生成不包含指定 key 的类型
+ * 与 Omit<T, Keys> 的区别是
  */
+export type ExcludeKeys<T, ExcludeKeys> = Pick<T, {
+    [K in keyof T]: K extends ExcludeKeys ? never : K;
+}[keyof T]>;
+/** 排除对象的方法（仅保留属性） */
 export type ExcluceMethods<T> = ExcludePropertiesOfType<T, Function>;
-/**
- * 所有“可能失败”的操作都可使用此类型作为返回值
- */
-export interface Success<T = void> {
-    success: true;
-    data: T;
-}
-export interface Failed<ET = string> {
-    success: false;
-    error: ET;
-    code?: number | string;
-}
-export type MaySuccess<T = void, ET = string> = Success<T> | Failed<ET>;
-declare function success(): Success;
-declare function success<T>(data: T): Success<T>;
-export { success };
-export declare function failed<ET>(error: ET, code?: number | string): Failed<ET>;
-/**
- * 若传入值为 success，格式化其 data；否则原样返回错误
- * 支持传入会返回 MaySuccess 的 Promise
- */
-declare function formatSuccess<T, ET, FT>(item: MaySuccess<T, ET>, formatter: (data: T) => FT): MaySuccess<FT, ET>;
-declare function formatSuccess<T, ET, FT>(item: Promise<MaySuccess<T, ET>>, formatter: (data: T) => FT): Promise<MaySuccess<FT, ET>>;
-export { formatSuccess };
 /**
  * 确认变量是否有值
  * 注意：空字符串和数字 0 也会判定为没有值
@@ -83,9 +54,7 @@ export { formatSuccess };
 declare function truthy(value: string | number | boolean | null | undefined): value is string | number | true;
 declare function truthy<T>(value: T | string | number | boolean | null | undefined): value is T | string | number | true;
 export { truthy };
-/**
- * 定义 JSON 数据
- */
+/** 定义 JSON 数据 */
 export type JSONData = number | boolean | string | null | JSONData[] | {
     [key: string]: JSONData;
 };

package/lang/types.js

@@ -14,19 +14,6 @@
 export function tuple(...elements) {
     return elements;
 }
-function success(data) {
-    return { success: true, data };
-}
-export { success };
-export function failed(error, code) {
-    return { success: false, error, code };
-}
-function formatSuccess(item, formatter) {
-    if ('then' in item)
-        return item.then(finalItem => formatSuccess(finalItem, formatter));
-    return item.success ? { ...item, data: formatter(item.data) } : item;
-}
-export { formatSuccess };
 function truthy(value) {
     return value !== null && value !== undefined && value !== '' && value !== 0 && value !== false;
 }

package/md5.d.ts

@@ -0,0 +1,30 @@
+/**
+ * MD5 算法来自：https://github.com/emn178/js-md5
+ */
+export declare function md5(content: string | ArrayBuffer): string;
+/**
+ * 使用方法：
+ * const md5 = new MD5()
+ * md5.update(xxx)  // 对于大文件，可以拆分开，多次调用 md5.update()
+ * const hash = md5.hex()
+ */
+export declare class MD5 {
+    private readonly buffer8;
+    private readonly blocks;
+    private h0;
+    private h1;
+    private h2;
+    private h3;
+    private start;
+    private bytes;
+    private hBytes;
+    private lastByteIndex;
+    private finalized;
+    private hashed;
+    private first;
+    constructor();
+    update(message: string | number[] | Uint8Array | ArrayBuffer): void;
+    private finalize;
+    private hash;
+    hex(): string;
+}