ts-utils 插件介绍

• ts-utils 插件介绍
  • 1. 概要说明
    • 1.1 地址
    • 1.2 插件描述
    • 1.3 重要依赖
    • 1.4 插件安装
  • 2. 包说明, 直接查看声明文件即可
  • 3. 示例

1. 概要说明

1.1 地址

https://gitee.com/duqingbing/ts-v3-package/tree/ts-v3-utils

1.2 插件描述

vite + ts 构建的基础函数库, 使用 vue 在本项目中辅助测试功能

1.3 重要依赖

• copy-to-clipboard: ^3.3.3
• js-base64: ^3.7.7
• js-cookie: ^3.0.5
• vue: ^3.4.21

1.4 插件安装

# yarn 安装
yarn add @qingbing/ts-v3-utils

# npm 安装
npm i @qingbing/ts-v3-utils

2. 包说明, 直接查看声明文件即可

import { CookieAttributes } from 'js-cookie';

/**
 * 事件(函数)独占
 */
export declare class Alone {
    static instance(): Alone;
    private _isRunning;
    /**
     * 事件开始执行函数
     * @param cb 回调函数
     * @param runningTipMessage 执行中的提示信息
     */
    start(cb: TCallableVoid): void;
    /**
     * @returns boolean 是否正在执行
     */
    isRunning(): boolean;
    /**
     * 事件结束必须执行
     * @param cb 回调函数
     */
    over(cb?: TCallableVoid): void;
}

export declare class Base64 {
    /**
     * base64 编码
     * @param str any 需要编码的字符
     * @returns string 编码后字符
     */
    static encode(str: any, urlSafe?: boolean): string;
    /**
     * base64 URI 编码
     * @param str any 需要编码的字符
     * @returns string 编码后字符
     */
    static encodeURI(str: any): string;
    /**
     * base64 URL 编码
     * @param str any 需要编码的字符
     * @returns string 编码后字符
     */
    static encodeURL(str: any): string;
    /**
     * base64 解码
     * @param data string
     * @returns any
     */
    static decode(data: string): any;
}

export declare class Col {
    /**
     * 遍历集合
     *
     * @param kvs 需要循环遍历的对象， 主要用于 object, array, set, map
     * @param callbackfn 返回 false 表示终止循环
     */
    static each<K, V, T extends IEach<K, V> | object>(kvs: T, callbackfn: (value: V | T[Extract<keyof T, string>], key: K | Extract<keyof T, string>, all: T) => boolean | void): void;
    /**
     * 查找集合中字段的值
     *
     * @param kvs 需要循环遍历的对象， 可是 array, set, map
     * @param key 查询的 key
     * @param defaultVal 默认值
     * @returns
     */
    static value<K, V, T extends IEach<K, V> | object>(kvs: T, key: K, defaultVal?: V | null): V | null;
    /**
     * 查找所有匹配的对象， 并构建新的对象
     *
     * @param kvs 需要循环遍历的对象
     * @param keys 查询的 keys
     * @returns
     */
    static values(kvs: TObject, keys: PropertyKey[]): TObject;
    /**
     * 从二维表中挑选两列，一列作为 key ， 一列作为 value, 组成一个 IRecord
     *
     * @param items 类似 db 的二维数据表
     * @param keyName
     * @param valueName
     * @param defaultVal
     * @returns
     */
    static column(items: TRecord[], keyName: any, valueName: any, defaultVal?: any): TObject;
}

/**
 * 将字符串拷贝到剪贴板中， 需要使用到 window
 * @param text 拷贝的字符串
 * @param opts 拷贝选项
 * @returns boolean
 */
export declare const CopyToClipboard: (text: string, opts?: TCopyClipboardOptions) => boolean;

/**
 * 类型转换模块
 */
export declare class Data {
    /**
     * string 转变为 number
     * @param s 需要转换的字符串
     * @returns
     */
    static StoI(s: string): number;
    /**
     * number 转变为 string
     * @param i number 需要转换的数字
     * @returns
     */
    static ItoS(i: number): string;
    /**
     * object 转换成 array
     * @param obj 需要转换的 object
     * @returns
     */
    static OtoA<T extends object>(obj: T): T[Extract<keyof T, string>][];
    /**
     * array 转变为 map
     * @param a 需要转换的数组
     * @returns
     */
    static AtoO<T>(a: T[]): TObject;
}

/**
 * 日期数据转换成时间戳 毫秒
 * @param date 日期
 * @returns
 */
export declare const date2Timestamp: (date?: Date) => number;

declare enum Dict {
    permanent = "permanent",
    value = "__VALUE__",
    expire = "__EXPIRE__"
}

/**
 * 文件下载
 */
export declare class Download {
    /**
     * 获取下载实例
     * @param charset string 下载文件字符集
     * @returns Download
     */
    static instance(charset?: string): Download;
    private _charset;
    private constructor();
    /**
     * 设置下载文件字符集
     * @returns Download
     */
    setCharset(charset: string): Download;
    private _blobText?;
    /**
     * 设置下载的 blob 内容
     * @param text
     * @returns Download
     */
    setBlobText(text: unknown): Download;
    private _mine;
    private _extension;
    /**
     * 设置下载文件后缀
     * @param extension
     * @returns Download
     */
    setExtension(extension: string | null): Download;
    private _filename;
    /**
     * 设置下载文件名
     * @param extension
     * @returns Download
     */
    setFilename(filename: string): Download;
    /**
     * 手动创建文件名
     * @returns Download
     */
    generateFilename(): Download;
    /**
     * @returns string 获取保存文件名
     */
    private getFilename;
    /**
     * 文件下载
     */
    download(): void;
}

/**
 * 打印相关函数
 */
export declare class Dump {
    /**
     * 打印错误信息
     * @param {String} msg 错误消息
     */
    static error(msg: TMessage): void;
    /**
     * 打印消息
     */
    static log(message?: any, ...optionalParams: any[]): void;
    /**
     * 打印提示消息
     */
    static info(message?: any, ...optionalParams: any[]): void;
    /**
     * 打印警告信息
     */
    static warn(message?: any, ...optionalParams: any[]): void;
    /**
     * @returns 返回 console 对象
     */
    static console(): Console;
}

/**
 * 将变量分割成数组
 *
 * @param {mixed} val
 * @param {string} delimiter
 */
export declare function explode(val: string | string[], delimiter?: string): string[];

/**
 * 日期格式化, 替换字符串参考
 *    Y,y: 年; M,m: 月; D,d: 日; H,h: 时; I,i: 分; S,s: 秒; A,a: 毫秒
 * @param val
 * @param format 格式标志
 * @returns
 */
export declare const formatDate: (val?: number | string, format?: string) => string;

/**
 * 控制页面的逻辑幂等
 */
export declare class Idempotent {
    static instance(): Idempotent;
    private static _runningKeys;
    _runningMsg: string;
    /**
     * 设置幂等处理消息
     * @param msg
     * @returns
     */
    setRunningMsg(msg: string): this;
    /**
     * 执行幂等逻辑
     * @param uk 唯一key
     * @param callback 回调函数， 其参数的需要在幂等执行完后手动执行，用于关闭当前程序执行
     * @param obj
     */
    run(uk: TKey, callback: (cb: TCallableVoid) => void, obj?: any): void;
}

export declare interface IEach<K, V> {
    forEach(callbackfn: (value: V, key: K) => void, thisArg?: any): void;
}

/**
 * 判断一个值是否在一个数组中
 * @param arr
 * @param val
 * @returns
 */
export declare const inArray: <T>(arr: T[], val: T) => boolean;

/**
 * 判断一个变量是否是数组
 * @param v
 * @returns
 */
export declare const isArray: (v: unknown) => v is unknown[];

/**
 * 判断一个变量是否是bool类型
 * @param v
 * @returns
 */
export declare const isBoolean: (v: unknown) => v is boolean;

/**
 * 判断当前环境是否是 development 环境
 */
export declare const isDev: () => boolean;

/**
 * 判断一个变量是否为空
 * @param v
 * @returns
 */
export declare const isEmpty: (v: any) => boolean;

/**
 * 判断一个变量是否是函数
 * @param v
 * @returns
 */
export declare const isFunction: (v: unknown) => v is Function;

export declare const isIEach: <K, V>(obj: any) => obj is IEach<K, V>;

/**
 * 判断一个变量是否是 NULL
 * @param v
 * @returns
 */
export declare const isNull: (v: unknown) => v is null;

/**
 * 判断一个变量是否是数字类型
 * @param v
 * @returns
 */
export declare const isNumber: (v: unknown) => v is number;

/**
 * 判断一个变量是否是Object
 * @param v
 * @returns
 */
export declare const isObject: (v: unknown) => v is Record<any, any>;

/**
 * 返回给定数据是否属于一个分页结构
 * @param v any
 * @returns boolean
 */
export declare const isPagingData: (v: any) => v is TPagingResult<any>;

/**
 * 判断一个变量是否是 {} 对象
 * @param v
 * @returns
 */
export declare const isPlainObject: (v: unknown) => v is object;

/**
 * 判断一个变量是否是 promise 对象
 * @param v
 * @returns
 */
export declare const isPromise: <T = any>(v: unknown) => v is Promise<T>;

/**
 * 判断给定数据是否属于一个远端返回
 *
 * @param v any
 * @returns boolean
 */
export declare const isResult: (v: any) => v is TResult<any>;

/**
 * 判断一个变量是否是 string 类型
 * @param v
 * @returns
 */
export declare const isString: (v: unknown) => v is string;

/**
 * 判断一个变量是否是 symbol
 * @param v
 * @returns
 */
export declare const isSymbol: (v: unknown) => v is symbol;

/**
 * 判断一个变量是否是 undefined 类型
 * @param v
 * @returns
 */
export declare const isUndefined: (v: unknown) => v is undefined;

export declare class Json {
    /**
     * json 编码
     * @param str any 需要编码的字符
     * @returns string 编码后字符
     */
    static encode(str: any): string;
    /**
     * json 解码
     * @param data string
     * @returns any
     */
    static decode(data: string): any;
}

/**
 * array 或 object 的混入
 * @param setting object | array
 * @param objs
 * @returns
 */
export declare const mixins: (setting: any, ...objs: unknown[]) => any;

/**
 * 异步获取远程数据
 *
 * @param {Object | Array} promises
 * @param {Function | undefined} callback
 * @param {Function | null | undefined} dataCallback
 */
export declare const PromiseAll: <T extends object>(promises: T) => Promise<T>;

/**
 * 获取 hex 形式的随机颜色值
 * @param alpha 是否添加透明色
 * @returns
 */
export declare const randomColor: (alpha?: boolean) => string;

/**
 * 获取范围内的随机数
 */
export declare const randomInt: (max?: number, min?: number, precision?: number) => number;

/**
 * 字符串对象替换
 * replace("{field} 必须介于 {min} 和 {max} 之间, 性别在 {sex} 之中", {field: "年龄",min: 18,max: 65,sex: ["male", "female"]})
 */
export declare const replace: (msg: string, kvs: TRecord, leftSymbol?: string, rightSymbol?: string) => string;

/**
 * 字符串占位替换
 * sprintf("%% %s 必须介于 %d 和 %d 之间, 性别在 %j 之中", "年龄", 18, 65, ["male", "female"])
 */
export declare const sprintf: (...params: any) => string;

/**
 * 带有有效期的数据存储
 */
declare abstract class storage {
    protected static buildResult<T>(isValid: boolean, message: string, value: T | null): TStorageResult<T | null>;
    protected static encodeValue<T>(value: T, expire?: TExpire): string;
    protected static decodeValue<T>(value: string): TStorageResult<T | null>;
}

export declare type TCallableVoid = () => void;

export declare type TCopyClipboardOptions = {
    debug?: boolean;
    message?: string;
    format?: string;
    onCopy?: (clipboardData: object) => void;
};

export declare type TExpire = Dict.permanent | number;

/**
 * 毫秒转换成日期数据
 * @param timestamp 毫秒
 * @returns
 */
export declare const timestamp2Date: (timestamp?: number) => Date;

export declare type TKey = string;

export declare type TMessage = string;

export declare type TObject = Record<PropertyKey, any>;

/**
 * 将变量（json字符串）转换成json对象
 */
export declare const toJson: (v: unknown) => any | null;

export declare type TRecord = Record<string, any>;

export declare type TPagingData<T> = {
    pageSize?: number;
    pageNo?: number;
    total?: number;
    data: T[];
};

export declare type TPagingResult<T> = Omit<TResult<T>, "data"> & {
    data: TPagingData<T>;
};

/**
 * 后段数据相应接口接口
 */
export declare type TResult<T> = {
    msg?: string;
    code: number | string;
    data?: T;
};

declare type TStorageResult<T> = {
    isValid: boolean;
    message: string | null;
    value: T | null;
};

export declare type TStringCallableVoid = (v: string) => void;

export declare type TTitle = string;

declare type TXzFetchData = (key?: TKey) => unknown;

/**
 * 生成唯一的UUID
 */
export declare const uniqid: () => string;

/**
 * Make all properties in T writable
 */
export declare type Writable<T> = {
    -readonly [P in keyof T]: T[P];
};

/**
 * 使用 js-cookie(document.cookie) 封装的缓存
 */
export declare class XzCookie {
    /**
     * 获取 document.cookie 信息
     * @param key storage-key
     * @returns
     */
    static getOrSave<T>(key: TKey, fetchCall?: TXzFetchData, duration?: number, setting?: Partial<CookieAttributes>): Promise<T>;
    /**
     * 获取 document.cookie 信息
     * @param key storage-key
     * @returns
     */
    static get<T>(key: TKey): T;
    /**
     * 保存 document.cookie 信息, 可以设置有效时间(秒)
     * @param key storage-key
     * @param value
     * @param duration 秒
     * @param setting
     */
    static set<T>(key: TKey, value: T, duration?: number, setting?: Partial<CookieAttributes>): T;
    /**
     * 保存 document.cookie 信息，同时设置有效期(日期)
     * @param key storage-key
     * @param value 保存信息
     * @param expire 有效期(时间戳)
     */
    static setAt<T>(key: TKey, value: T, expire?: Date, setting?: Partial<CookieAttributes>): T;
    /**
     * 删除 document.cookie 信息
     * @param key storage-key
     * @param key
     */
    static remove(key: TKey): void;
    /**
     * 清空 document.cookie 信息
     */
    static clear(): void;
}

/**
 * 使用 localStorage 封装的缓存
 */
export declare class XzLocal extends storage {
    /**
     * 获取 localStorage 信息
     * @param key storage-key
     * @returns
     */
    static getOrSave<T>(key: TKey, fetchCall?: TXzFetchData, ops?: {
        duration?: number;
        expire?: TExpire;
    }): Promise<TStorageResult<T | null>>;
    /**
     * 获取 localStorage 信息
     * @param key storage-key
     * @returns
     */
    static get<T>(key: TKey): TStorageResult<T | null>;
    /**
     * 保存 localStorage 信息， 可以设置保存时间(秒)
     * @param key storage-key
     * @param value 保存信息
     * @param duration number 保存时效(秒)
     */
    static set<T>(key: TKey, value: T, duration?: number): TStorageResult<T | null>;
    /**
     * 保存 localStorage 信息，同时设置有效期(时间戳)
     * @param key storage-key
     * @param value 保存信息
     * @param expire 有效期(时间戳)
     */
    static setAt<T>(key: TKey, value: T, expire?: TExpire): TStorageResult<T | null>;
    /**
     * 删除 localStorage 信息
     * @param key storage-key
     * @param key
     */
    static remove(key: TKey): void;
    /**
     * 清空 localStorage 信息
     */
    static clear(): void;
}

/**
 * 使用 sessionStorage 封装的缓存
 */
export declare class XzSession extends storage {
    /**
     * 获取 sessionStorage 信息
     * @param key storage-key
     * @returns
     */
    static getOrSave<T>(key: TKey, fetchCall?: TXzFetchData): Promise<TStorageResult<T | null>>;
    /**
     * 获取 sessionStorage 信息
     * @param key storage-key
     * @returns
     */
    static get<T>(key: TKey): TStorageResult<T | null>;
    /**
     * 保存 sessionStorage 信息
     * @param key storage-key
     * @param value
     */
    static set<T>(key: TKey, value: T): TStorageResult<T | null>;
    /**
     * 删除 sessionStorage 信息
     * @param key storage-key
     * @param key
     */
    static remove(key: TKey): void;
    /**
     * 清空 sessionStorage 信息
     */
    static clear(): void;
}

3. 示例

该库函数众多,不便垒述,具体的示例参考 src/test 里面的测试文件, 每一个函数,方法,类 都能找到对应的测试示例, 直接复制参考即可.