@yiero/gmlib/dist/Storage/GmArrayStorage.d.ts

GM Lib for Tampermonkey/ScriptCat

import { GmStorage } from './GmStorage.ts';
/**
 * 数组类型油猴存储管理类
 *
 * 继承自 GmStorage，专门用于处理数组类型的数据存储。
 * 提供数组操作方法（push、pop、map、filter 等），确保存储的值始终是数组类型。
 *
 * @warn 需要授权函数 `GM_getValue`、`GM_setValue`、`GM_deleteValue`、
 *       `GM_addValueChangeListener`、`GM_removeValueChangeListener`
 *
 * @example
 * ```ts
 * // 创建待办事项存储
 * const todoStorage = new GmArrayStorage<{ task: string; done: boolean }>(
 *   'todo_list',
 *   [{ task: '示例任务', done: false }]
 * );
 *
 * // 添加任务
 * todoStorage.push({ task: '新任务', done: false });
 *
 * // 获取数组长度
 * console.log(todoStorage.length);
 * ```
 */
export declare class GmArrayStorage<T> extends GmStorage<Array<T>> {
    constructor(key: string, defaultValue?: Array<T>);
    /**
     * 获取当前存储的值（返回浅拷贝以保护 defaultValue）
     *
     * @alias get()
     */
    get value(): Array<T>;
    /**
     * 获取数组长度
     *
     * @returns 数组元素数量
     */
    get length(): number;
    /**
     * 获取数组最后一项
     *
     * @returns 最后一个元素，数组为空时返回 undefined
     */
    get lastItem(): T | undefined;
    /**
     * 获取数组第一项
     *
     * @returns 第一个元素，数组为空时返回 undefined
     */
    get firstItem(): T | undefined;
    /**
     * 获取当前存储的值（返回浅拷贝以保护 defaultValue）
     *
     * @returns 数组的浅拷贝
     */
    get(): Array<T>;
    /**
     * 设置值
     *
     * @param value - 新的数组值
     */
    set(value: Array<T>): void;
    /**
     * 基于索引修改数组项
     *
     * @param value - 新值
     * @param index - 索引位置
     * @throws RangeError 当索引越界时抛出
     *
     * @example
     * ```ts
     * const storage = new GmArrayStorage('test', [1, 2, 3]);
     * storage.modify(10, 1); // [1, 10, 3]
     * storage.modify(20, 5); // 抛出 RangeError
     * ```
     */
    modify(value: T, index: number): void;
    /**
     * 清空储存为默认值
     */
    reset(): void;
    /**
     * 清空储存为空数组
     */
    clear(): void;
    /**
     * 基于索引删除数组项
     *
     * @param index - 要删除的索引位置
     * @throws RangeError 当索引越界时抛出
     *
     * @example
     * ```ts
     * const storage = new GmArrayStorage('test', [1, 2, 3]);
     * storage.removeAt(1); // [1, 3]
     * ```
     */
    removeAt(index: number): void;
    /**
     * 基于索引删除数组项
     *
     * @param index - 要删除的索引位置
     * @throws RangeError 当索引越界时抛出
     * @deprecated 使用 {@link removeAt} 替代
     */
    delete(index: number): void;
    /**
     * 向数组末尾添加一项
     *
     * @param value - 要添加的值
     */
    push(value: T): void;
    /**
     * 向数组末尾批量添加多项
     *
     * @param values - 要添加的值
     *
     * @example
     * ```ts
     * const storage = new GmArrayStorage('test', [1]);
     * storage.pushMany(2, 3, 4); // [1, 2, 3, 4]
     * ```
     */
    pushMany(...values: T[]): void;
    /**
     * 删除数组最后一项
     *
     * @returns 被删除的元素，数组为空时返回 undefined
     */
    pop(): T | undefined;
    /**
     * 向数组开头添加一项
     *
     * @param value - 要添加的值
     */
    unshift(value: T): void;
    /**
     * 向数组开头批量添加多项
     *
     * @param values - 要添加的值
     *
     * @example
     * ```ts
     * const storage = new GmArrayStorage('test', [4]);
     * storage.unshiftMany(1, 2, 3); // [1, 2, 3, 4]
     * ```
     */
    unshiftMany(...values: T[]): void;
    /**
     * 删除数组第一项
     *
     * @returns 被删除的元素，数组为空时返回 undefined
     */
    shift(): T | undefined;
    /**
     * 遍历数组（不修改存储）
     *
     * @param callback - 遍历回调函数
     */
    forEach(callback: (value: T, index: number, array: T[]) => void): void;
    /**
     * 映射数组（不修改存储），返回新数组
     *
     * @typeParam U - 返回数组元素类型
     * @param callback - 映射回调函数
     * @returns 映射后的新数组
     *
     * @example
     * ```ts
     * const storage = new GmArrayStorage('test', [1, 2, 3]);
     * const doubled = storage.map(x => x * 2); // [2, 4, 6]
     * console.log(storage.value); // [1, 2, 3] 原数组不变
     * ```
     */
    map<U>(callback: (value: T, index: number, array: T[]) => U): U[];
    /**
     * 映射数组并更新存储
     *
     * @param callback - 映射回调函数
     *
     * @example
     * ```ts
     * const storage = new GmArrayStorage('test', [1, 2, 3]);
     * storage.mapInPlace(x => x * 2);
     * console.log(storage.value); // [2, 4, 6]
     * ```
     */
    mapInPlace(callback: (value: T, index: number, array: T[]) => T): void;
    /**
     * 过滤数组（不修改存储），返回新数组
     *
     * @param callback - 过滤回调函数
     * @returns 过滤后的新数组
     *
     * @example
     * ```ts
     * const storage = new GmArrayStorage('test', [1, 2, 3, 4]);
     * const evens = storage.filter(x => x % 2 === 0); // [2, 4]
     * console.log(storage.value); // [1, 2, 3, 4] 原数组不变
     * ```
     */
    filter(callback: (value: T, index: number, array: T[]) => boolean): T[];
    /**
     * 过滤数组并更新存储
     *
     * @param callback - 过滤回调函数
     *
     * @example
     * ```ts
     * const storage = new GmArrayStorage('test', [1, 2, 3, 4]);
     * storage.filterInPlace(x => x % 2 === 0);
     * console.log(storage.value); // [2, 4]
     * ```
     */
    filterInPlace(callback: (value: T, index: number, array: T[]) => boolean): void;
    /**
     * 查找满足条件的第一个元素
     *
     * @param callback - 条件回调函数
     * @returns 找到的元素，未找到时返回 undefined
     */
    find(callback: (value: T, index: number, array: T[]) => boolean): T | undefined;
    /**
     * 查找满足条件的第一个元素的索引
     *
     * @param callback - 条件回调函数
     * @returns 找到的索引，未找到时返回 -1
     */
    findIndex(callback: (value: T, index: number, array: T[]) => boolean): number;
    /**
     * 检查数组是否包含指定元素
     *
     * @param value - 要检查的值
     * @returns 是否包含
     */
    includes(value: T): boolean;
    /**
     * 查找指定元素的第一个索引
     *
     * @param value - 要查找的值
     * @returns 找到的索引，未找到时返回 -1
     */
    indexOf(value: T): number;
    /**
     * 截取数组片段（不修改存储）
     *
     * @param start - 起始索引
     * @param end - 结束索引（不含）
     * @returns 截取的数组片段
     */
    slice(start?: number, end?: number): T[];
    /**
     * 拼接另一个数组（不修改存储）
     *
     * @param items - 要拼接的数组
     * @returns 拼接后的新数组
     */
    concat(...items: ConcatArray<T>[]): T[];
    /**
     * 判断数组是否为空
     *
     * @returns 是否为空
     */
    isEmpty(): boolean;
    /**
     * 获取指定索引的元素
     *
     * @param index - 索引位置（支持负数索引）
     * @returns 元素值，越界时返回 undefined
     *
     * @example
     * ```ts
     * const storage = new GmArrayStorage('test', [1, 2, 3]);
     * storage.at(0);  // 1
     * storage.at(-1); // 3
     * storage.at(5);  // undefined
     * ```
     */
    at(index: number): T | undefined;
    /**
     * 校验索引是否有效
     *
     * @param index - 要校验的索引
     * @param methodName - 调用方法名（用于错误信息）
     * @throws RangeError 当索引越界时抛出
     */
    private validateIndex;
}