@composy/store-core 0.0.1

package/esm/types/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @lkit/store-core 类型定义
+ *
+ * 提供状态管理的核心类型定义
+ * @module types
+ */
+export * from './store';
+export * from './plugin';
+export * from './middleware';
+export * from './subscription';
+export * from './utility';
+//# sourceMappingURL=index.d.ts.map

package/esm/types/middleware.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 中间件系统类型定义
+ *
+ * @module types/middleware
+ */
+import type { StateTree, StoreId } from './store';
+/**
+ * 中间件上下文
+ * @template S - 状态类型
+ */
+export interface MiddlewareContext<S extends StateTree = StateTree> {
+    /** Store ID */
+    storeId: StoreId;
+    /** 当前状态 */
+    state: S;
+    /** 操作类型 */
+    type: MiddlewareActionType;
+    /** 操作数据 */
+    payload?: unknown;
+    /** 元数据 */
+    meta?: Record<string, unknown>;
+}
+/**
+ * 中间件操作类型
+ */
+export type MiddlewareActionType = 'state:init' | 'state:patch' | 'state:reset' | 'action:before' | 'action:after' | 'action:error';
+/**
+ * 中间件函数类型
+ * @template S - 状态类型
+ */
+export type MiddlewareFunction<S extends StateTree = StateTree> = (context: MiddlewareContext<S>, next: () => void | Promise<void>) => void | Promise<void>;
+/**
+ * 中间件接口
+ * @template S - 状态类型
+ */
+export interface Middleware<S extends StateTree = StateTree> {
+    /** 中间件名称 */
+    readonly name: string;
+    /** 中间件优先级（数字越小越先执行） */
+    readonly priority?: number;
+    /** 中间件处理函数 */
+    handler: MiddlewareFunction<S>;
+}
+/**
+ * 中间件管理器接口
+ */
+export interface MiddlewareManager {
+    /**
+     * 添加中间件
+     * @param middleware - 中间件实例
+     */
+    use: (middleware: Middleware) => void;
+    /**
+     * 移除中间件
+     * @param name - 中间件名称
+     */
+    remove: (name: string) => void;
+    /**
+     * 获取中间件
+     * @param name - 中间件名称
+     */
+    get: (name: string) => Middleware | undefined;
+    /**
+     * 是否存在中间件
+     * @param name - 中间件名称
+     */
+    has: (name: string) => boolean;
+    /**
+     * 执行中间件链
+     * @param context - 上下文
+     */
+    execute: (context: MiddlewareContext) => Promise<void>;
+    /**
+     * 获取所有中间件
+     */
+    getAll: () => Middleware[];
+    /**
+     * 清空所有中间件
+     */
+    clear: () => void;
+}
+/**
+ * 日志中间件选项
+ */
+export interface LoggerMiddlewareOptions {
+    /** 是否记录状态变化 */
+    logState?: boolean;
+    /** 是否记录 action */
+    logAction?: boolean;
+    /** 是否折叠日志 */
+    collapsed?: boolean;
+    /** 是否显示时间戳 */
+    timestamp?: boolean;
+    /** 日志级别 */
+    level?: 'log' | 'info' | 'warn' | 'debug';
+    /** 自定义日志器 */
+    logger?: {
+        log: (...args: unknown[]) => void;
+        info: (...args: unknown[]) => void;
+        warn: (...args: unknown[]) => void;
+        debug: (...args: unknown[]) => void;
+        error?: (...args: unknown[]) => void;
+        group?: (...args: unknown[]) => void;
+        groupCollapsed?: (...args: unknown[]) => void;
+        groupEnd?: () => void;
+    };
+    /** 自定义过滤器 */
+    filter?: (context: MiddlewareContext) => boolean;
+}
+/**
+ * 持久化中间件选项
+ */
+export interface PersistMiddlewareOptions {
+    /** 存储键名前缀 */
+    keyPrefix?: string;
+    /** 存储类型 */
+    storage?: 'localStorage' | 'sessionStorage';
+    /** 要持久化的 Store ID 列表（空则全部持久化） */
+    stores?: StoreId[];
+    /** 要持久化的状态路径 */
+    paths?: Record<StoreId, string[]>;
+    /** 序列化函数 */
+    serialize?: (value: unknown) => string;
+    /** 反序列化函数 */
+    deserialize?: (value: string) => unknown;
+    /** 防抖延迟（毫秒） */
+    debounce?: number;
+}
+/**
+ * 时间旅行中间件选项
+ */
+export interface TimeTravelMiddlewareOptions {
+    /** 最大历史记录数 */
+    maxHistory?: number;
+    /** 是否启用 */
+    enabled?: boolean;
+}
+/**
+ * 时间旅行控制器
+ */
+export interface TimeTravelController {
+    /** 撤销 */
+    undo: () => void;
+    /** 重做 */
+    redo: () => void;
+    /** 跳转到指定历史 */
+    goto: (index: number) => void;
+    /** 获取历史记录 */
+    getHistory: () => StateSnapshot[];
+    /** 当前历史索引 */
+    getCurrentIndex: () => number;
+    /** 是否可撤销 */
+    canUndo: () => boolean;
+    /** 是否可重做 */
+    canRedo: () => boolean;
+    /** 清空历史 */
+    clear: () => void;
+}
+/**
+ * 状态快照
+ */
+export interface StateSnapshot {
+    /** 快照时间 */
+    timestamp: number;
+    /** 状态数据 */
+    state: StateTree;
+    /** 操作类型 */
+    type: MiddlewareActionType;
+    /** Store ID */
+    storeId: StoreId;
+}
+//# sourceMappingURL=middleware.d.ts.map

package/esm/types/plugin.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 插件系统类型定义
+ *
+ * @module types/plugin
+ */
+import type { StateTree, StoreId } from './store';
+/**
+ * 插件上下文
+ */
+export interface PluginContext {
+    /** Store 管理器实例 */
+    storeManager: StoreManagerLike;
+    /** 当前 Store ID */
+    storeId: StoreId;
+    /** 当前 Store 实例 */
+    store: unknown;
+    /** 插件配置选项 */
+    options: Record<string, unknown>;
+}
+/**
+ * Store 管理器接口（简化版）
+ */
+export interface StoreManagerLike {
+    /** 获取 Store */
+    getStore: (id: StoreId) => unknown;
+    /** 是否存在 Store */
+    hasStore: (id: StoreId) => boolean;
+    /** 获取所有 Store ID */
+    getStoreIds: () => StoreId[];
+}
+/**
+ * 插件接口
+ * @template Options - 插件选项类型
+ */
+export interface StorePlugin<Options = Record<string, unknown>> {
+    /** 插件名称 */
+    readonly name: string;
+    /** 插件版本 */
+    readonly version?: string;
+    /** 插件描述 */
+    readonly description?: string;
+    /**
+     * 安装插件
+     * @param context - 插件上下文
+     * @param options - 插件选项
+     */
+    install: (context: PluginContext, options?: Options) => void | Promise<void>;
+    /**
+     * 卸载插件
+     * @param context - 插件上下文
+     */
+    uninstall?: (context: PluginContext) => void | Promise<void>;
+    /**
+     * Store 创建时的钩子
+     * @param store - Store 实例
+     */
+    onStoreCreated?: (store: unknown) => void;
+    /**
+     * Store 销毁时的钩子
+     * @param store - Store 实例
+     */
+    onStoreDisposed?: (store: unknown) => void;
+    /**
+     * 状态变化时的钩子
+     * @param storeId - Store ID
+     * @param state - 新状态
+     * @param oldState - 旧状态
+     */
+    onStateChange?: <S extends StateTree>(storeId: StoreId, state: S, oldState: S) => void;
+}
+/**
+ * 插件工厂函数类型
+ * @template Options - 插件选项类型
+ */
+export type PluginFactory<Options = Record<string, unknown>> = (options?: Options) => StorePlugin<Options>;
+/**
+ * 定义插件选项
+ * @template Options - 插件选项类型
+ */
+export interface DefinePluginOptions<Options = Record<string, unknown>> {
+    /** 插件名称 */
+    name: string;
+    /** 插件版本 */
+    version?: string;
+    /** 插件描述 */
+    description?: string;
+    /** 安装函数 */
+    install: StorePlugin<Options>['install'];
+    /** 卸载函数 */
+    uninstall?: StorePlugin<Options>['uninstall'];
+    /** Store 创建钩子 */
+    onStoreCreated?: StorePlugin<Options>['onStoreCreated'];
+    /** Store 销毁钩子 */
+    onStoreDisposed?: StorePlugin<Options>['onStoreDisposed'];
+    /** 状态变化钩子 */
+    onStateChange?: StorePlugin<Options>['onStateChange'];
+}
+/**
+ * 插件管理器接口
+ */
+export interface PluginManager {
+    /**
+     * 注册插件
+     * @param plugin - 插件实例
+     * @param options - 插件选项
+     */
+    use: <Options>(plugin: StorePlugin<Options>, options?: Options) => void;
+    /**
+     * 移除插件
+     * @param name - 插件名称
+     */
+    remove: (name: string) => void;
+    /**
+     * 获取插件
+     * @param name - 插件名称
+     */
+    get: (name: string) => StorePlugin | undefined;
+    /**
+     * 是否已注册插件
+     * @param name - 插件名称
+     */
+    has: (name: string) => boolean;
+    /**
+     * 获取所有插件
+     */
+    getAll: () => Map<string, StorePlugin>;
+    /**
+     * 获取插件数量
+     */
+    size: () => number;
+    /**
+     * 清空所有插件
+     */
+    clear: () => void;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/esm/types/store.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Store 核心类型定义
+ *
+ * @module types/store
+ */
+/**
+ * 状态对象类型
+ */
+export type StateTree = Record<string | number | symbol, unknown>;
+/**
+ * Store ID 类型
+ */
+export type StoreId = string;
+/**
+ * Getter 函数类型
+ * @template S - 状态类型
+ * @template R - 返回值类型
+ */
+export type StoreGetter<S extends StateTree, R> = (state: S) => R;
+/**
+ * Getter 集合类型
+ * @template S - 状态类型
+ */
+export type StoreGetters<S extends StateTree> = Record<string, StoreGetter<S, unknown>>;
+/**
+ * Action 函数类型
+ *
+ * 允许 action 通过 `this` 访问当前 Store 实例；未使用 `this` 的普通函数依旧兼容。
+ */
+export type StoreAction = (...args: unknown[]) => unknown;
+/**
+ * Action 集合类型
+ */
+export type StoreActions = Record<string, StoreAction>;
+/**
+ * Store 定义选项
+ * @template Id - Store ID 类型
+ * @template S - 状态类型
+ * @template G - Getters 类型
+ * @template A - Actions 类型
+ */
+export interface StoreDefinition<Id extends StoreId = StoreId, S extends StateTree = StateTree, G extends StoreGetters<S> = StoreGetters<S>, A extends StoreActions = StoreActions> {
+    /** Store 唯一标识 */
+    id: Id;
+    /** 初始状态工厂函数 */
+    state: () => S;
+    /** Getters 定义 */
+    getters?: G;
+    /** Actions 定义 */
+    actions?: A;
+}
+/**
+ * Store 实例接口
+ * @template Id - Store ID 类型
+ * @template S - 状态类型
+ * @template G - Getters 类型
+ * @template A - Actions 类型
+ */
+export interface StoreInstance<Id extends StoreId = StoreId, S extends StateTree = StateTree, G extends StoreGetters<S> = StoreGetters<S>, A extends StoreActions = StoreActions> {
+    /** Store 唯一标识 */
+    $id: Id;
+    /** 当前状态 */
+    $state: S;
+    /** Getter 计算结果 */
+    getters: {
+        [K in keyof G]: ReturnType<G[K]>;
+    };
+    /** Action 方法集合 */
+    actions: A;
+    /**
+     * 重置状态到初始值
+     */
+    $reset: () => void;
+    /**
+     * 批量更新状态
+     * @param partialState - 部分状态或更新函数
+     */
+    $patch: (partialState: Partial<S> | ((state: S) => void)) => void;
+    /**
+     * 订阅状态变化
+     * @param callback - 回调函数
+     * @param options - 订阅选项
+     * @returns 取消订阅函数
+     */
+    $subscribe: (callback: StateSubscriber<S>, options?: SubscribeOptions) => () => void;
+    /**
+     * 订阅 action 调用
+     * @param callback - 回调函数
+     * @returns 取消订阅函数
+     */
+    $onAction: (callback: ActionSubscriber<A>) => () => void;
+    /**
+     * 销毁 store
+     */
+    $dispose: () => void;
+}
+/**
+ * 状态变化订阅器
+ * @template S - 状态类型
+ */
+export type StateSubscriber<S extends StateTree> = (mutation: StateMutation<S>, state: S) => void;
+/**
+ * 状态变化信息
+ * @template S - 状态类型
+ */
+export interface StateMutation<S extends StateTree> {
+    /** 变化类型 */
+    type: 'direct' | 'patch object' | 'patch function';
+    /** Store ID */
+    storeId: StoreId;
+    /** 变化的键路径 */
+    events?: string[];
+    /** 变化前的状态快照 */
+    oldState?: Partial<S>;
+}
+/**
+ * 订阅选项
+ */
+export interface SubscribeOptions {
+    /** 是否立即执行一次 */
+    immediate?: boolean;
+    /** 是否深度监听 */
+    deep?: boolean;
+    /** 是否在组件卸载后继续监听 */
+    detached?: boolean;
+}
+/**
+ * Action 订阅器
+ * @template A - Actions 类型
+ */
+export type ActionSubscriber<A extends StoreActions> = (context: ActionContext<A>) => void;
+/**
+ * Action 上下文
+ * @template A - Actions 类型
+ */
+export interface ActionContext<A extends StoreActions> {
+    /** Action 名称 */
+    name: keyof A;
+    /** Store ID */
+    storeId: StoreId;
+    /** 调用参数 */
+    args: unknown[];
+    /** 执行后回调，异步 action 会在 Promise resolve 后触发 */
+    after: (callback: (result: unknown) => void | Promise<void>) => void;
+    /** 错误回调，异步 action 会在 Promise reject 后触发 */
+    onError: (callback: (error: unknown) => void | Promise<void>) => void;
+}
+/**
+ * Store 配置选项
+ */
+export interface StoreOptions {
+    /** 是否启用严格模式（只能通过 action 修改状态） */
+    strict?: boolean;
+    /** 是否启用开发工具 */
+    devtools?: boolean;
+    /** 是否启用持久化 */
+    persist?: boolean;
+    /** 持久化配置 */
+    persistOptions?: PersistOptions;
+}
+/**
+ * 持久化选项
+ */
+export interface PersistOptions {
+    /** 存储键名 */
+    key?: string;
+    /** 存储类型 */
+    storage?: 'localStorage' | 'sessionStorage' | 'custom';
+    /** 自定义存储适配器 */
+    customStorage?: StorageAdapter;
+    /** 要持久化的路径 */
+    paths?: string[];
+    /** 序列化函数 */
+    serializer?: {
+        serialize: (value: unknown) => string;
+        deserialize: (value: string) => unknown;
+    };
+    /** 恢复前回调 */
+    beforeRestore?: (context: {
+        store: unknown;
+    }) => void;
+    /** 恢复后回调 */
+    afterRestore?: (context: {
+        store: unknown;
+    }) => void;
+}
+/**
+ * 存储适配器接口
+ */
+export interface StorageAdapter {
+    /** 获取数据 */
+    getItem: (key: string) => string | null | Promise<string | null>;
+    /** 设置数据 */
+    setItem: (key: string, value: string) => void | Promise<void>;
+    /** 删除数据 */
+    removeItem: (key: string) => void | Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/esm/types/subscription.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 订阅系统类型定义
+ *
+ * @module types/subscription
+ */
+import type { StateTree, StoreId } from './store';
+/**
+ * 订阅回调类型
+ * @template T - 数据类型
+ */
+export type Subscriber<T = unknown> = (value: T, oldValue?: T) => void;
+/**
+ * 取消订阅函数类型
+ */
+export type Unsubscribe = () => void;
+/**
+ * 订阅选项
+ */
+export interface SubscriptionOptions {
+    /** 是否立即执行 */
+    immediate?: boolean;
+    /** 是否在 store 销毁后保持订阅 */
+    detached?: boolean;
+}
+/**
+ * 发布订阅管理器接口
+ */
+export interface PubSub<T = unknown> {
+    /**
+     * 订阅
+     * @param callback - 回调函数
+     * @param options - 订阅选项
+     * @returns 取消订阅函数
+     */
+    subscribe: (callback: Subscriber<T>, options?: SubscriptionOptions) => Unsubscribe;
+    /**
+     * 发布
+     * @param value - 新值
+     * @param oldValue - 旧值
+     */
+    publish: (value: T, oldValue?: T) => void;
+    /**
+     * 清空所有订阅
+     */
+    clear: () => void;
+    /**
+     * 获取订阅者数量
+     */
+    size: () => number;
+}
+/**
+ * 事件类型
+ */
+export type EventType = 'store:created' | 'store:disposed' | 'state:changed' | 'action:called' | 'action:completed' | 'action:error' | 'plugin:installed' | 'plugin:uninstalled';
+/**
+ * 事件数据
+ */
+export interface EventData {
+    /** 事件类型 */
+    type: EventType;
+    /** Store ID */
+    storeId?: StoreId;
+    /** 事件数据 */
+    payload?: unknown;
+    /** 时间戳 */
+    timestamp: number;
+}
+/**
+ * 事件监听器类型
+ */
+export type EventListener = (data: EventData) => void;
+/**
+ * 事件总线接口
+ */
+export interface EventBus {
+    /**
+     * 监听事件
+     * @param type - 事件类型
+     * @param listener - 监听器
+     * @returns 取消监听函数
+     */
+    on: (type: EventType | '*', listener: EventListener) => Unsubscribe;
+    /**
+     * 监听一次
+     * @param type - 事件类型
+     * @param listener - 监听器
+     * @returns 取消监听函数
+     */
+    once: (type: EventType, listener: EventListener) => Unsubscribe;
+    /**
+     * 取消监听
+     * @param type - 事件类型
+     * @param listener - 监听器
+     */
+    off: (type: EventType | '*', listener?: EventListener) => void;
+    /**
+     * 发送事件
+     * @param type - 事件类型
+     * @param payload - 事件数据
+     */
+    emit: (type: EventType, payload?: unknown) => void;
+    /**
+     * 清空所有监听器
+     */
+    clear: () => void;
+}
+/**
+ * 选择器函数类型
+ * @template S - 状态类型
+ * @template R - 返回值类型
+ */
+export type Selector<S extends StateTree, R> = (state: S) => R;
+/**
+ * 选择器订阅选项
+ */
+export interface SelectorOptions<R> {
+    /** 是否立即执行 */
+    immediate?: boolean;
+    /** 相等性比较函数 */
+    equalityFn?: (a: R, b: R) => boolean;
+}
+/**
+ * 批量更新上下文
+ */
+export interface BatchContext {
+    /** 是否正在批量更新 */
+    isBatching: boolean;
+    /** 待更新的 Store ID 列表 */
+    pendingStores: Set<StoreId>;
+}
+/**
+ * 批量更新管理器接口
+ */
+export interface BatchManager {
+    /**
+     * 开始批量更新
+     */
+    start: () => void;
+    /**
+     * 结束批量更新并通知所有订阅者
+     */
+    end: () => void;
+    /**
+     * 标记 Store 需要更新
+     * @param storeId - Store ID
+     */
+    markDirty: (storeId: StoreId) => void;
+    /**
+     * 在批量上下文中执行
+     * @param fn - 执行函数
+     */
+    batch: <T>(fn: () => T) => T;
+    /**
+     * 是否正在批量更新
+     */
+    isBatching: () => boolean;
+}
+//# sourceMappingURL=subscription.d.ts.map