@cmtlyt/lingshu-toolkit 0.2.0 → 0.4.0

package/dist/shared/animation/utils.js

@@ -0,0 +1,134 @@
+import { throwType } from "../throw-error/index.js";
+import { getType } from "../utils/base.js";
+import { withResolvers } from "../with-resolvers/index.js";
+function getNextValueHandler(from, to, valueFormatter) {
+    const type = getType(from);
+    const context = {
+        progress: 0,
+        valueFormatter
+    };
+    const baseNextValue = (_from, _to)=>{
+        const { valueFormatter: formatter, progress } = context;
+        if ('number' !== getType(_from)) return _from;
+        return formatter(_from + (_to - _from) * progress);
+    };
+    const arrayHandler = (_from, _to)=>{
+        const result = Array.from(_from, (item, idx)=>{
+            if (Array.isArray(item)) return arrayHandler(item, _to[idx]);
+            if ('object' === getType(item)) return objectHandler(item, _to[idx]);
+            return baseNextValue(item, _to[idx]);
+        });
+        return result;
+    };
+    const objectHandler = (_from, _to)=>{
+        const result = {};
+        const keys = Reflect.ownKeys(_from);
+        for(let i = 0; i < keys.length; i++){
+            const key = keys[i];
+            const fromValue = _from[key];
+            const toValue = _to[key];
+            if (Array.isArray(_from[key])) result[key] = arrayHandler(fromValue, toValue);
+            else if ('object' === getType(fromValue)) result[key] = objectHandler(fromValue, toValue);
+            else result[key] = baseNextValue(fromValue, toValue);
+        }
+        return result;
+    };
+    let nextValueHandler = baseNextValue;
+    if ('array' === type) nextValueHandler = arrayHandler;
+    else if ('object' === type) nextValueHandler = objectHandler;
+    return (progress)=>{
+        context.progress = progress;
+        return nextValueHandler(from, to);
+    };
+}
+function matchValid(from, to, valueParser) {
+    const fromType = getType(from);
+    const toType = getType(to);
+    if (fromType !== toType) throwType('animation/stepAnimation', 'from and to must be the same type');
+    if ('array' === fromType) {
+        if (from.length !== to.length) throwType('animation/stepAnimation', 'from and to must be the same length');
+        const result = [
+            Array.from({
+                length: from.length
+            }),
+            Array.from({
+                length: to.length
+            })
+        ];
+        for(let i = 0; i < from.length; i++){
+            const [fromItem, toItem] = matchValid(from[i], to[i], valueParser);
+            result[0][i] = fromItem;
+            result[1][i] = toItem;
+        }
+        return result;
+    }
+    if ('object' === fromType) {
+        const toKeys = Reflect.ownKeys(to);
+        const fromKeys = new Set(Reflect.ownKeys(from));
+        const result = [
+            {},
+            {}
+        ];
+        for(let i = 0; i < toKeys.length; i++){
+            const key = toKeys[i];
+            if (!fromKeys.has(key)) throwType('animation/stepAnimation', `from does not have this key: ${String(key)}`);
+            const [fromItem, toItem] = matchValid(from[key], to[key], valueParser);
+            result[0][key] = fromItem;
+            result[1][key] = toItem;
+        }
+        return result;
+    }
+    if ('number' !== fromType) return [
+        valueParser(from),
+        valueParser(to)
+    ];
+    return [
+        from,
+        to
+    ];
+}
+function createNextTick(resolvers, rcSignal) {
+    const nextTick = (()=>{
+        if ('function' == typeof globalThis.requestAnimationFrame) return globalThis.requestAnimationFrame;
+        return (callback)=>setTimeout(callback, 16);
+    })();
+    return (callback)=>{
+        if (rcSignal.stopSignal) return true;
+        nextTick(()=>tryRun(callback, resolvers, (error)=>{
+                rcSignal.stop();
+                resolvers.reject(error);
+            }));
+        return false;
+    };
+}
+async function tryRun(callback, resolvers, customErrorHandler) {
+    return new Promise((resolve, reject)=>{
+        const result = callback();
+        if (result && 'function' == typeof result.then) return result.then(resolve, reject);
+        resolve();
+    }).catch(customErrorHandler || resolvers.reject);
+}
+function createRunningControllerSignal(startFn, options) {
+    const { onStart, onStop, onClear } = options;
+    const resolvers = withResolvers();
+    const ctrl = {
+        stopSignal: true,
+        resolvers,
+        stop: ()=>{
+            ctrl.stopSignal = true;
+            onStop();
+        },
+        start: ()=>{
+            ctrl.stopSignal = false;
+            onStart();
+            startFn();
+        },
+        clear: ()=>{
+            ctrl.stopSignal = true;
+            onClear();
+            resolvers.resolve(true);
+        }
+    };
+    return ctrl;
+}
+export { createNextTick, createRunningControllerSignal, getNextValueHandler, matchValid, tryRun };

package/dist/shared/condition-merge/index.d.ts

@@ -1,4 +1,4 @@
-import type { IsPrimitive, UnionToIntersection } from '../types';
+import type { IsPrimitive, Printify, UnionToIntersection } from '../types';
 type AssertValue = Record<PropertyKey, any> | any[];
 type ConditionArrayItem = [boolean, AssertValue, AssertValue?];
 type ConditionObjItem = {
@@ -25,11 +25,7 @@ type MergedResult<T extends ConditionItem[]> = T extends [
     ...infer Last extends [ConditionItem, ...ConditionItem[]]
 ] ? ParseConditionValue<First> & MergedResult<Last> : ParseConditionValue<T[0]>;
 type CMInput = ConditionItem[];
-type Printify<T> = T extends any[] ? T : [T] extends [never] ? T : {
-    [K in keyof T]: T[K];
-};
 type FormatResult<T extends any[]> = T[0] & Record<PropertyKey, any>;
 export declare function conditionMerge<T extends CMInput>(...input: T): FormatResult<MergedResult<T>>;
 export declare function conditionMerge<T extends CMInput>(input: T): FormatResult<MergedResult<T>>;
 export {};
-t {};

package/dist/shared/create-storage-handler/index.browser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/create-storage-handler/index.d.ts

@@ -0,0 +1,10 @@
+export interface CreateStorageOptions {
+    storageType: 'local' | 'session' | 'memory';
+    autoSaveInterval: number;
+}
+export interface StorageHandler<T extends Record<string, any>> {
+    get: <K extends keyof T | (string & {})>(key?: K) => string extends K ? T : T[K & keyof T];
+    set: <K extends keyof T | (string & {})>(value: string extends K ? T : T[K & keyof T], key?: K) => void;
+    clear: () => void;
+}
+export declare function createStorageHandler<T extends Record<string, any>>(storageKey: string, initialData?: T, options?: Partial<CreateStorageOptions>): StorageHandler<T>;

package/dist/shared/create-storage-handler/index.js

@@ -0,0 +1,68 @@
+import { $dt, $t, dataHandler } from "../data-handler/index.js";
+import { logger } from "../logger/index.js";
+import { throwError } from "../throw-error/index.js";
+const validInfo = $dt({
+    storageKey: 'validString',
+    storageType: $t["enum"]([
+        'local',
+        'session',
+        'memory'
+    ], 'local'),
+    autoSaveInterval: $t.number(0)
+});
+const memoryStorage = {
+    data: {},
+    getItem (key) {
+        return this.data[key];
+    },
+    setItem (key, value) {
+        this.data[key] = value;
+    },
+    removeItem (key) {
+        delete this.data[key];
+    }
+};
+function getStorage(storageType) {
+    try {
+        if ('memory' === storageType) return memoryStorage;
+        return 'local' === storageType ? localStorage : sessionStorage;
+    } catch  {
+        logger.warn('createStorage', 'Failed to access localStorage or sessionStorage, using memoryStorage instead.');
+        return memoryStorage;
+    }
+}
+const CLEAR_FLAG = Symbol('cleared');
+function createStorageHandler(storageKey, initialData, options = {}) {
+    const { storageKey: validStorageKey, storageType, autoSaveInterval } = dataHandler({
+        storageKey,
+        ...options
+    }, validInfo, {
+        unwrap: true
+    });
+    const storage = getStorage(storageType);
+    const storageData = storage.getItem(validStorageKey);
+    const context = {
+        data: storageData ? JSON.parse(storageData) : initialData || {}
+    };
+    return {
+        get (key) {
+            if (context.data === CLEAR_FLAG) throwError('createStorageHandler', 'Storage has been cleared.');
+            if (null == key) return context.data;
+            return context.data[key];
+        },
+        set (value, key) {
+            if (context.data === CLEAR_FLAG) throwError('createStorageHandler', 'Storage has been cleared.');
+            if (null == key) context.data = value;
+            else context.data[key] = value;
+            if (autoSaveInterval > 0) setTimeout(()=>{
+                storage.setItem(validStorageKey, JSON.stringify(context.data));
+            }, autoSaveInterval);
+            else storage.setItem(validStorageKey, JSON.stringify(context.data));
+        },
+        clear () {
+            context.data = CLEAR_FLAG;
+            storage.removeItem(validStorageKey);
+        }
+    };
+}
+export { createStorageHandler };

package/dist/shared/create-storage-handler/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/data-handler/index.d.ts

@@ -1,6 +1,11 @@
+import type { Equal, Printify } from '../types';
+import type { Transform2Type } from './tools';
 import type { DataHandlerOptions, Handler } from './types';
-export declare function dataHandler<M extends Record<PropertyKey, any>, O extends DataHandlerOptions<M> = DataHandlerOptions<M>>(data: M & Partial<O['defaultValue']>, handler: Handler<M>, options?: O): O['unwrap'] extends true ? M & O['defaultValue'] : {
-    result: M & O['defaultValue'];
+type MergeResult<BaseResult extends Record<PropertyKey, any>, HandlerResult extends Handler<any>> = Printify<HandlerResult extends (...args: any[]) => any ? BaseResult : BaseResult & {
+    [K in keyof HandlerResult]: Equal<HandlerResult[K], any> extends true ? Required<BaseResult>[K] : HandlerResult[K];
+}>;
+export declare function dataHandler<M extends Record<PropertyKey, any>, H extends Handler<M> = Handler<M>, O extends DataHandlerOptions<M> = DataHandlerOptions<M>>(data: M & Partial<O['defaultValue']>, handler: H, options?: O): O['unwrap'] extends true ? MergeResult<M & O['defaultValue'], Transform2Type<H>> : {
+    result: MergeResult<M & O['defaultValue'], Transform2Type<H>>;
     errors: string[];
 };
 export * from './tools';

package/dist/shared/data-handler/tools.d.ts

@@ -1,18 +1,42 @@
 import type { Handler } from './types';
 type TypeHandler = NonNullable<Exclude<Handler<any>, (...args: any[]) => any>[string]>;
-type Fullback = ((_v: any) => any) | (any & {});
+type TypeHandlerParams = Parameters<TypeHandler> extends [any, ...infer Rest] ? Rest : never;
+type ParseType<T extends string> = T extends keyof TypeMap ? TypeMap[T] : any;
+type TypeHandlerInfo<T extends string> = (value: ParseType<T>, ...args: TypeHandlerParams) => ReturnType<TypeHandler>;
+interface TypeMap {
+    notNullable: any & {};
+    string: string;
+    validString: string;
+    number: number;
+    validNumber: number;
+    boolean: boolean;
+    object: Record<PropertyKey, any>;
+    array: any[];
+    function: (...args: any[]) => any;
+    symbol: symbol;
+    enum: any & {};
+}
 export declare const $t: {
-    notNullable: (fullback?: Fullback) => TypeHandler;
-    string: (fullback?: Fullback) => TypeHandler;
-    validString: (fullback?: Fullback) => TypeHandler;
-    number: (fullback?: Fullback) => TypeHandler;
-    validNumber: (fullback?: Fullback) => TypeHandler;
-    boolean: (fullback?: Fullback) => TypeHandler;
-    object: (fullback?: Fullback) => TypeHandler;
-    array: (fullback?: Fullback) => TypeHandler;
-    function: (fullback?: Fullback) => TypeHandler;
-    symbol: (fullback?: Fullback) => TypeHandler;
+    notNullable: (fullback?: any) => TypeHandlerInfo<"notNullable">;
+    string: (fullback?: string | ((_v: any) => string) | undefined) => TypeHandlerInfo<"string">;
+    validString: (fullback?: string | ((_v: any) => string) | undefined) => TypeHandlerInfo<"validString">;
+    number: (fullback?: number | ((_v: any) => number) | undefined) => TypeHandlerInfo<"number">;
+    validNumber: (fullback?: number | ((_v: any) => number) | undefined) => TypeHandlerInfo<"validNumber">;
+    boolean: (fullback?: boolean | ((_v: any) => boolean) | undefined) => TypeHandlerInfo<"boolean">;
+    object: (fullback?: Record<PropertyKey, any> | ((_v: any) => Record<PropertyKey, any>) | undefined) => TypeHandlerInfo<"object">;
+    array: (fullback?: any[] | ((_v: any) => any[]) | undefined) => TypeHandlerInfo<"array">;
+    function: (fullback?: ((_v: any) => (...args: any[]) => any) | undefined) => TypeHandlerInfo<"function">;
+    symbol: (fullback?: symbol | ((_v: any) => symbol) | undefined) => TypeHandlerInfo<"symbol">;
+    enum: <T>(list: T[], fullback?: T) => TypeHandlerInfo<"enum">;
 };
-export declare function defineTransform<T extends Record<PropertyKey, any>>(dataInfo: Partial<Record<keyof T, keyof typeof $t | TypeHandler>>): Record<PropertyKey, (value: any, action: import("./types").Actions, option: any) => false | (any & {})>;
+type TransformMap = typeof $t;
+type TransformKey = Exclude<keyof TransformMap, 'enum'>;
+type DataTransformResult<D extends Record<PropertyKey, TransformKey | TypeHandler | undefined>> = {
+    [K in keyof D]: D[K] extends TransformKey ? TransformMap[D[K]] : D[K];
+};
+export type Transform2Type<R extends DataTransformResult<any>> = {
+    [K in keyof R]: R[K] extends TypeHandlerInfo<infer T> ? ParseType<T> & {} : any & {};
+};
+export declare function defineTransform<T extends Record<PropertyKey, any>, D extends Partial<Record<keyof T, TransformKey | TypeHandler>> = Partial<Record<keyof T, TransformKey | TypeHandler>>>(dataInfo: D): DataTransformResult<D>;
 export declare const $dt: typeof defineTransform;
 export {};

package/dist/shared/data-handler/tools.js

@@ -1,7 +1,6 @@
 import { logger } from "../logger/index.js";
-function getType(_v) {
-    return Object.prototype.toString.call(_v).slice(8, -1).toLowerCase();
-}
+import { throwType } from "../throw-error/index.js";
+import { getType } from "../utils/base.js";
 function typeHandler(type, verifyFn) {
     return (fullback)=>(_v, actions)=>{
             if (verifyFn ? verifyFn(_v) : getType(_v) === type) return true;
@@ -21,7 +20,12 @@ const $t = {
     object: typeHandler('object'),
     array: typeHandler('array'),
     function: typeHandler('function'),
-    symbol: typeHandler('symbol')
+    symbol: typeHandler('symbol'),
+    enum: (list, fullback)=>{
+        if (!Array.isArray(list)) throwType('$t.enum', 'list must be an array');
+        const set = new Set(list);
+        return typeHandler('enum', (_v)=>set.has(_v))(fullback);
+    }
 };
 function defineTransform(dataInfo) {
     const verifyInfo = {};

package/dist/shared/data-handler/types.d.ts

@@ -8,8 +8,8 @@ export interface Actions {
     transform: <T>(value: T) => T;
 }
 export type Handler<M extends Record<PropertyKey, any>> = Partial<{
-    [K in keyof M]: (value: M[K], action: Actions, option: M) => false | (any & {});
-}> | (<K extends keyof M>(value: M[K], key: K, action: Actions, option: M) => false | (any & {}));
+    [K in keyof M]: (value: any, action: Actions, option: M) => false | (any & {});
+}> | (<K extends keyof M>(value: any, key: K, action: Actions, option: M) => false | (any & {}));
 export interface ActionContext {
     errors: string[];
     transforms: [PropertyKey, any][];

package/dist/shared/data-mixed-manager/__test__/basic.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/data-mixed-manager/__test__/build-options.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/data-mixed-manager/__test__/constructor-options.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/data-mixed-manager/__test__/data-management.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/data-mixed-manager/__test__/edge-cases.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/data-mixed-manager/__test__/events.browser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/data-mixed-manager/__test__/events.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/data-mixed-manager/__test__/fixed-slots.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/data-mixed-manager/__test__/insert-mode.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/data-mixed-manager/constants.d.ts

@@ -0,0 +1,8 @@
+export declare const SLOT_TYPE: {
+    readonly fixed: {
+        readonly fixedFlag: symbol;
+    };
+    readonly insert: {
+        readonly insertFlag: symbol;
+    };
+};

package/dist/shared/data-mixed-manager/constants.js

@@ -0,0 +1,9 @@
+const SLOT_TYPE = {
+    fixed: {
+        fixedFlag: Symbol('fixed')
+    },
+    insert: {
+        insertFlag: Symbol('insert')
+    }
+};
+export { SLOT_TYPE };

package/dist/shared/data-mixed-manager/index.d.ts

@@ -0,0 +1,128 @@
+import type { PickRequired } from '../types/base';
+import type { BuildOptions, DataMixedManagerOptions, DMMEventHandler, EventDetailMap, InputSlotConfig, MixedDataItem } from './types';
+/**
+ * 通用数据管理器类
+ * 支持定坑逻辑处理，不包含具体业务逻辑
+ *
+ * @template T - 数据类型
+ */
+declare class DataMixedManager<T> extends EventTarget {
+    addEventListener<E extends keyof EventDetailMap<T>>(type: E, listener: DMMEventHandler<T, E> | null, options?: AddEventListenerOptions | boolean): void;
+    removeEventListener<E extends keyof EventDetailMap<T>>(type: E, listener: DMMEventHandler<T, E> | null, options?: EventListenerOptions | boolean): void;
+    /** 实例配置 */
+    private readonly options;
+    /** 位置到定坑配置的映射 */
+    private readonly fixedSlots;
+    /** 普通数据列表 */
+    private readonly dataList;
+    /** 混合后的数据 */
+    private readonly mixedData;
+    /** 最后混合的定坑位置 */
+    private lastMixedSlotIdx;
+    /** 上次处理的数据长度 */
+    private prevDataLength;
+    /** 是否正在批量更新 */
+    private isBatching;
+    constructor(options?: DataMixedManagerOptions<T>);
+    /**
+     * 初始化事件监听
+     * @param listener - 事件监听
+     */
+    private initListener;
+    private getTypeText;
+    private buildSlotConfig;
+    /**
+     * 添加定坑配置
+     * @param config - 定坑配置
+     * @param buildOptions - 构建选项
+     * @returns 返回添加后的定坑位置
+     */
+    addFixedSlot(config: InputSlotConfig<T>, buildOptions?: BuildOptions): number;
+    /**
+     * 重新排序定坑位置
+     * 当插入模式为 before 或 after 时，需要调整后续定坑的位置
+     * @param config - 定坑配置
+     * @returns 返回调整后的定坑配置
+     */
+    private reorderFixedSlots;
+    /**
+     * 批量添加定坑配置
+     * @param configs - 定坑配置数组
+     * @param buildOptions - 构建选项
+     * @returns 返回添加后的定坑位置数组
+     */
+    addFixedSlots(configs: InputSlotConfig<T>[], buildOptions?: BuildOptions): number[];
+    /**
+     * 移除指定位置的定坑配置
+     * @param position - 要移除的定坑位置
+     * @param buildOptions - 构建选项
+     */
+    deleteFixedSlot(position: number, buildOptions?: BuildOptions): void;
+    /**
+     * 批量移除定坑配置
+     * @param positions - 要移除的定坑位置数组
+     * @param buildOptions - 构建选项
+     */
+    deleteFixedSlots(positions: number[], buildOptions?: BuildOptions): void;
+    /**
+     * 批量更新
+     * @param callback - 更新回调
+     */
+    private batchUpdate;
+    /**
+     * 清除所有定坑配置
+     * @param buildOptions - 构建选项
+     */
+    clearFixedSlots(buildOptions?: BuildOptions): void;
+    /**
+     * 追加新的数据列表到普通数据列表末尾
+     * @param list - 要追加的数据数组
+     * @param buildOptions - 构建选项，lazy 为 true 时延迟构建
+     */
+    appendList(list: T[], buildOptions?: BuildOptions): void;
+    /**
+     * 清空普通数据列表
+     */
+    clearList(): void;
+    /**
+     * 获取混合后的数据
+     * @param buildOptions - 构建选项
+     * @returns 返回混合后的数据项数组
+     */
+    getMixedData(buildOptions?: Omit<BuildOptions, 'lazy'>): MixedDataItem<T>[];
+    /**
+     * 分发事件
+     * 同时在实例和 window 对象上触发事件
+     * @param name - 事件名称
+     * @param data - 事件数据
+     */
+    private dispatch;
+    /**
+     * 重新构建混合数据
+     * 全局定坑：定坑位置始终固定在全局位置，普通数据在定坑位置之外填充
+     * 定坑位置不会因为普通数据的变化而改变
+     */
+    private buildMixedData;
+    /**
+     * 切片获取指定范围内的定坑位置
+     * @param startIdx - 起始位置
+     * @param endIdx - 结束位置，默认为正无穷
+     * @returns 返回过滤后的定坑位置数组
+     */
+    private sliceSlots;
+    /**
+     * 插入数据（插卡模式）
+     * 在指定位置插入数据，会触发全量重建
+     * @param config - 定坑配置，必须指定插入模式
+     * @returns 返回插入后的实际位置
+     */
+    insertSlot(config: PickRequired<InputSlotConfig<T>, 'insertMode'>): number;
+    insertSlots(configs: PickRequired<InputSlotConfig<T>, 'insertMode'>[]): number[];
+}
+/**
+ * 创建数据管理器实例的工厂函数
+ * @template T - 数据类型
+ * @returns 返回一个新的 DataMixedManager 实例
+ */
+export declare function dataMixedManager<T>(options?: DataMixedManagerOptions<T>): DataMixedManager<T>;
+export {};