@composy/store-core 0.0.1 → 0.0.2

package/esm/utils/deep-clone.d.ts

@@ -1,143 +0,0 @@
-/**
- * 深拷贝工具
- *
- * 提供高性能的深拷贝、浅拷贝和深度合并功能
- * @module utils/deep-clone
- */
-/**
- * 判断是否为对象
- *
- * @param value - 待检查的值
- * @returns 是否为对象
- */
-export declare function isObject(value: unknown): value is Record<string, unknown>;
-/**
- * 判断是否为普通对象（非数组、非内置对象）
- *
- * @param value - 待检查的值
- * @returns 是否为普通对象
- */
-export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
-/**
- * 深拷贝配置选项
- */
-export interface DeepCloneOptions {
-    /** 是否优先使用 structuredClone（默认 true） */
-    useStructuredClone?: boolean;
-    /** 是否克隆函数（默认 false，函数保持引用） */
-    cloneFunctions?: boolean;
-    /** 是否克隆 Symbol 属性（默认 false） */
-    cloneSymbols?: boolean;
-    /** 最大深度（默认无限制） */
-    maxDepth?: number;
-    /** 自定义克隆器 */
-    customCloner?: <T>(value: T, clone: <U>(v: U) => U) => T | undefined;
-}
-/**
- * 深拷贝
- *
- * 高性能深拷贝实现，优先使用原生 structuredClone（如果可用）
- *
- * @template T - 值类型
- * @param value - 要拷贝的值
- * @param options - 配置选项
- * @returns 拷贝后的值
- *
- * @example
- * ```typescript
- * const obj = { a: 1, b: { c: 2 } }
- * const cloned = deepClone(obj)
- * cloned.b.c = 3
- * console.log(obj.b.c) // 2
- * ```
- *
- * @example
- * ```typescript
- * // 带配置的深拷贝
- * const cloned = deepClone(obj, {
- *   maxDepth: 5,
- *   cloneSymbols: true
- * })
- * ```
- */
-export declare function deepClone<T>(value: T, options?: DeepCloneOptions): T;
-/**
- * 浅拷贝
- *
- * @template T - 值类型
- * @param value - 要拷贝的值
- * @returns 拷贝后的值
- *
- * @example
- * ```typescript
- * const arr = [1, 2, { a: 3 }]
- * const cloned = shallowClone(arr)
- * cloned[2].a = 4
- * console.log(arr[2].a) // 4 (浅拷贝，嵌套对象共享引用)
- * ```
- */
-export declare function shallowClone<T>(value: T): T;
-/**
- * 深度合并配置选项
- */
-export interface DeepMergeOptions {
-    /** 数组合并策略：'replace' 替换 | 'concat' 连接 | 'merge' 按索引合并 */
-    arrayStrategy?: 'replace' | 'concat' | 'merge';
-    /** 是否克隆源对象（默认 true） */
-    clone?: boolean;
-    /** 最大深度 */
-    maxDepth?: number;
-}
-/**
- * 深度合并对象
- *
- * 将多个源对象深度合并到目标对象
- *
- * @template T - 目标对象类型
- * @param target - 目标对象
- * @param sources - 源对象列表
- * @returns 合并后的对象
- *
- * @example
- * ```typescript
- * const target = { a: 1, b: { c: 2 } }
- * const source = { b: { d: 3 }, e: 4 }
- * const result = deepMerge(target, source)
- * // { a: 1, b: { c: 2, d: 3 }, e: 4 }
- * ```
- */
-export declare function deepMerge<T extends Record<string, unknown>>(target: T, ...sources: Array<Partial<T>>): T;
-/**
- * 带配置的深度合并
- *
- * @template T - 目标对象类型
- * @param target - 目标对象
- * @param options - 合并配置
- * @param sources - 源对象列表
- * @returns 合并后的对象
- */
-export declare function deepMergeWithOptions<T extends Record<string, unknown>>(target: T, options: DeepMergeOptions, ...sources: Array<Partial<T>>): T;
-/**
- * 比较两个值是否深度相等
- *
- * @param a - 第一个值
- * @param b - 第二个值
- * @returns 是否相等
- *
- * @example
- * ```typescript
- * deepEqual({ a: 1 }, { a: 1 }) // true
- * deepEqual([1, 2], [1, 2]) // true
- * deepEqual({ a: { b: 1 } }, { a: { b: 2 } }) // false
- * ```
- */
-export declare function deepEqual(a: unknown, b: unknown): boolean;
-/**
- * 冻结对象（深度）
- *
- * @template T - 对象类型
- * @param obj - 要冻结的对象
- * @returns 冻结后的对象
- */
-export declare function deepFreeze<T extends object>(obj: T): Readonly<T>;
-//# sourceMappingURL=deep-clone.d.ts.map

package/esm/utils/index.d.ts

@@ -1,13 +0,0 @@
-/**
- * 工具函数模块
- *
- * 提供深拷贝、选择器、路径操作等工具函数
- * @module utils
- */
-export { debounce, throttle, } from './debounce-throttle';
-export type { DebouncedFunction, ThrottledFunction, } from './debounce-throttle';
-export { deepClone, deepEqual, deepFreeze, deepMerge, deepMergeWithOptions, isObject, isPlainObject, shallowClone, } from './deep-clone';
-export type { DeepCloneOptions, DeepMergeOptions, } from './deep-clone';
-export { combineSelectors, createCachedSelector, createMemoizedSelector, createSelector, createSelectorWithDeps, deleteByPath, getByPath, hasPath, setByPath, } from './selector';
-export type { MemoizedSelectorOptions, SelectorEqualityFn, } from './selector';
-//# sourceMappingURL=index.d.ts.map

package/esm/utils/selector.d.ts

@@ -1,213 +0,0 @@
-/**
- * 状态选择器工具
- *
- * 提供高性能的状态选择器和路径操作工具
- * @module utils/selector
- */
-import type { Selector, StateTree } from '../types';
-/**
- * 选择器相等性比较函数类型
- */
-export type SelectorEqualityFn<R> = (a: R, b: R) => boolean;
-/**
- * 记忆化选择器配置选项
- */
-export interface MemoizedSelectorOptions<R> {
-    /** 相等性比较函数 */
-    equalityFn?: SelectorEqualityFn<R>;
-    /** 最大缓存大小（默认 1） */
-    maxSize?: number;
-    /** 是否在开发模式下记录缓存命中率 */
-    trackHitRate?: boolean;
-}
-/**
- * 创建记忆化选择器
- *
- * 基本的记忆化选择器，只缓存最后一次结果
- *
- * @template S - 状态类型
- * @template R - 返回值类型
- * @param selector - 选择器函数
- * @param equalityFn - 相等性比较函数（默认使用 Object.is）
- * @returns 记忆化的选择器
- *
- * @example
- * ```typescript
- * const selectTodos = createSelector(
- *   (state: AppState) => state.todos,
- * )
- *
- * const selectCompletedTodos = createSelector(
- *   (state: AppState) => state.todos.filter(t => t.completed),
- *   (a, b) => a.length === b.length && a.every((v, i) => v === b[i])
- * )
- * ```
- */
-export declare function createSelector<S extends StateTree, R>(selector: Selector<S, R>, equalityFn?: SelectorEqualityFn<R>): Selector<S, R>;
-/**
- * 创建带依赖的选择器
- *
- * 类似 reselect 的实现，支持多个输入选择器
- *
- * @template S - 状态类型
- * @template Deps - 依赖结果类型
- * @template R - 返回值类型
- * @param dependencies - 依赖选择器数组
- * @param combiner - 组合函数
- * @param options - 配置选项
- * @returns 记忆化的选择器
- *
- * @example
- * ```typescript
- * const selectVisibleTodos = createSelectorWithDeps(
- *   [
- *     (state) => state.todos,
- *     (state) => state.visibilityFilter,
- *   ],
- *   (todos, filter) => {
- *     switch (filter) {
- *       case 'SHOW_COMPLETED': return todos.filter(t => t.completed)
- *       case 'SHOW_ACTIVE': return todos.filter(t => !t.completed)
- *       default: return todos
- *     }
- *   }
- * )
- * ```
- */
-export declare function createSelectorWithDeps<S extends StateTree, Deps extends unknown[], R>(dependencies: {
-    [K in keyof Deps]: Selector<S, Deps[K]>;
-}, combiner: (...args: Deps) => R, options?: MemoizedSelectorOptions<R>): Selector<S, R>;
-/**
- * 组合多个选择器
- *
- * 简单的选择器组合，不带记忆化
- *
- * @template S - 状态类型
- * @template R - 结果类型数组
- * @template C - 组合结果类型
- * @param selectors - 选择器数组
- * @param combiner - 组合函数
- * @returns 组合后的选择器
- *
- * @example
- * ```typescript
- * const selectUserAndTodos = combineSelectors(
- *   [
- *     (state) => state.user,
- *     (state) => state.todos,
- *   ],
- *   (user, todos) => ({ user, todos })
- * )
- * ```
- */
-export declare function combineSelectors<S extends StateTree, R extends unknown[], C>(selectors: {
-    [K in keyof R]: Selector<S, R[K]>;
-}, combiner: (...results: R) => C): Selector<S, C>;
-/**
- * 创建带高级缓存的选择器
- *
- * 支持多个缓存条目，使用 LRU 策略
- *
- * @template S - 状态类型
- * @template R - 返回值类型
- * @param selector - 选择器函数
- * @param options - 配置选项
- * @returns 带缓存的选择器
- *
- * @example
- * ```typescript
- * const selectFilteredItems = createCachedSelector(
- *   (state, filter) => state.items.filter(item => item.type === filter),
- *   { maxSize: 5 }
- * )
- * ```
- */
-export declare function createCachedSelector<S extends StateTree, R>(selector: Selector<S, R>, options?: MemoizedSelectorOptions<R>): Selector<S, R> & {
-    clearCache: () => void;
-    getCacheSize: () => number;
-};
-/**
- * 创建记忆化选择器（别名，同 createSelector）
- *
- * @template S - 状态类型
- * @template R - 返回值类型
- * @param selector - 选择器函数
- * @param options - 配置选项
- * @returns 记忆化的选择器
- */
-export declare function createMemoizedSelector<S extends StateTree, R>(selector: Selector<S, R>, options?: MemoizedSelectorOptions<R>): Selector<S, R>;
-/**
- * 获取嵌套对象的值
- *
- * 支持点表示法和数组索引
- *
- * @template T - 返回值类型
- * @param obj - 对象
- * @param path - 路径（支持 'a.b.c' 或 'a[0].b'）
- * @param defaultValue - 默认值（当路径不存在时返回）
- * @returns 值
- *
- * @example
- * ```typescript
- * const value = getByPath({ a: { b: { c: 1 } } }, 'a.b.c')
- * // value: 1
- *
- * const arr = getByPath({ items: [{ name: 'test' }] }, 'items[0].name')
- * // arr: 'test'
- *
- * const missing = getByPath({ a: 1 }, 'b.c', 'default')
- * // missing: 'default'
- * ```
- */
-export declare function getByPath<T = unknown>(obj: unknown, path: string, defaultValue?: T): T | undefined;
-/**
- * 设置嵌套对象的值
- *
- * 支持自动创建中间路径
- *
- * @param obj - 对象
- * @param path - 路径
- * @param value - 值
- * @returns 是否成功
- *
- * @example
- * ```typescript
- * const obj = {}
- * setByPath(obj, 'a.b.c', 1)
- * // obj: { a: { b: { c: 1 } } }
- *
- * setByPath(obj, 'items[0].name', 'test')
- * // obj: { a: { b: { c: 1 } }, items: [{ name: 'test' }] }
- * ```
- */
-export declare function setByPath(obj: Record<string, unknown>, path: string, value: unknown): boolean;
-/**
- * 删除嵌套对象的值
- *
- * @param obj - 对象
- * @param path - 路径
- * @returns 是否成功删除
- *
- * @example
- * ```typescript
- * const obj = { a: { b: { c: 1 } } }
- * deleteByPath(obj, 'a.b.c')
- * // obj: { a: { b: {} } }
- * ```
- */
-export declare function deleteByPath(obj: Record<string, unknown>, path: string): boolean;
-/**
- * 检查嵌套对象中是否存在指定路径
- *
- * @param obj - 对象
- * @param path - 路径
- * @returns 是否存在
- *
- * @example
- * ```typescript
- * hasPath({ a: { b: 1 } }, 'a.b') // true
- * hasPath({ a: { b: 1 } }, 'a.c') // false
- * ```
- */
-export declare function hasPath(obj: unknown, path: string): boolean;
-//# sourceMappingURL=selector.d.ts.map

package/lib/core/async-action.d.ts

@@ -1,95 +0,0 @@
-/**
- * 异步 Action 工具
- *
- * 提供框架无关的异步操作状态管理
- * @module core/async-action
- */
-import type { Unsubscribe } from '../types';
-/**
- * 异步 Action 配置
- */
-export interface AsyncActionOptions {
-    /** 重试次数 (默认 0) */
-    retryCount?: number;
-    /** 重试间隔 (毫秒, 默认 1000) */
-    retryDelay?: number;
-    /** 超时时间 (毫秒, 0=不限) */
-    timeout?: number;
-    /** 执行前是否自动清除上次错误 */
-    resetOnExecute?: boolean;
-}
-/**
- * 异步 Action 状态
- */
-export interface AsyncActionState<T> {
-    /** 返回数据 */
-    data: T | null;
-    /** 错误信息 */
-    error: Error | null;
-    /** 是否加载中 */
-    loading: boolean;
-    /** 执行次数 */
-    executionCount: number;
-    /** 最后执行时间 */
-    lastExecutedAt: number | null;
-}
-/**
- * 异步 Action 实例
- */
-export interface AsyncAction<T, Args extends unknown[]> {
-    /** 当前状态 */
-    readonly state: AsyncActionState<T>;
-    /** 执行异步操作 */
-    execute: (...args: Args) => Promise<T>;
-    /** 重置状态 */
-    reset: () => void;
-    /** 取消当前执行 */
-    abort: () => void;
-    /** 订阅状态变化 */
-    subscribe: (callback: (state: AsyncActionState<T>) => void) => Unsubscribe;
-    /** 设置成功回调 */
-    onSuccess: (callback: (data: T) => void) => Unsubscribe;
-    /** 设置错误回调 */
-    onError: (callback: (error: Error) => void) => Unsubscribe;
-}
-/**
- * 创建异步 Action
- *
- * 将异步函数包装为带状态追踪的 Action，自动管理 loading/data/error 状态
- *
- * @template T - 返回数据类型
- * @template Args - 参数类型
- * @param fn - 异步函数
- * @param options - 配置选项
- * @returns AsyncAction 实例
- *
- * @example
- * ```typescript
- * // 基本用法
- * const fetchUsers = createAsyncAction(async (page: number) => {
- *   const res = await fetch(`/api/users?page=${page}`)
- *   return res.json()
- * })
- *
- * await fetchUsers.execute(1)
- * console.log(fetchUsers.state.data)    // 用户列表
- * console.log(fetchUsers.state.loading) // false
- *
- * // 带重试
- * const fetchWithRetry = createAsyncAction(
- *   async () => fetch('/api/unstable').then(r => r.json()),
- *   { retryCount: 3, retryDelay: 1000 }
- * )
- *
- * // 订阅状态变化
- * fetchUsers.subscribe((state) => {
- *   console.log('loading:', state.loading, 'data:', state.data)
- * })
- *
- * // 成功/错误回调
- * fetchUsers.onSuccess((data) => console.log('Got:', data))
- * fetchUsers.onError((err) => console.error('Failed:', err))
- * ```
- */
-export declare function createAsyncAction<T, Args extends unknown[] = []>(fn: (...args: Args) => Promise<T>, options?: AsyncActionOptions): AsyncAction<T, Args>;
-//# sourceMappingURL=async-action.d.ts.map

package/lib/core/base-store.d.ts

@@ -1,85 +0,0 @@
-/**
- * 基础 Store 抽象类
- *
- * 提供框架无关的 Store 基础实现
- * @module core/base-store
- */
-import type { ActionContext, ActionSubscriber, StateMutation, StateSubscriber, StateTree, StoreActions, StoreDefinition, StoreGetters, StoreId, StoreInstance, StoreOptions, SubscribeOptions, Unsubscribe } from '../types';
-/**
- * 基础 Store 类
- *
- * @template Id - Store ID 类型
- * @template S - 状态类型
- * @template G - Getters 类型
- * @template A - Actions 类型
- */
-export declare class BaseStore<Id extends StoreId = StoreId, S extends StateTree = StateTree, G extends StoreGetters<S> = StoreGetters<S>, A extends StoreActions = StoreActions> implements StoreInstance<Id, S, G, A> {
-    /** Store ID */
-    readonly $id: Id;
-    /** Getter 计算结果 */
-    readonly getters: {
-        [K in keyof G]: ReturnType<G[K]>;
-    };
-    /** Action 方法集合 */
-    readonly actions: A;
-    /** 状态订阅管理器 */
-    private stateSubscribers;
-    /** Action 订阅管理器 */
-    private actionSubscribers;
-    /** 初始状态工厂 */
-    private initialStateFactory;
-    /** 当前状态 */
-    private _state;
-    /** 是否已销毁 */
-    private disposed;
-    /**
-     * 构造函数
-     *
-     * @param definition - Store 定义
-     * @param _options - Store 配置选项
-     */
-    constructor(definition: StoreDefinition<Id, S, G, A>, _options?: StoreOptions);
-    /**
-     * 获取当前状态
-     */
-    get $state(): S;
-    /**
-     * 设置状态
-     */
-    set $state(newState: S);
-    /**
-     * 重置状态到初始值
-     */
-    $reset(): void;
-    /**
-     * 批量更新状态
-     */
-    $patch(partialState: Partial<S> | ((state: S) => void)): void;
-    /**
-     * 订阅状态变化
-     */
-    $subscribe(callback: StateSubscriber<S>, options?: SubscribeOptions): Unsubscribe;
-    /**
-     * 订阅 Action 调用
-     */
-    $onAction(callback: ActionSubscriber<A>): Unsubscribe;
-    /**
-     * 销毁 Store
-     */
-    $dispose(): void;
-    /**
-     * 通知状态变化
-     */
-    protected notifyStateChange(mutation: StateMutation<S>): void;
-    /**
-     * 通知 Action 调用
-     */
-    protected notifyAction(context: ActionContext<A>): void;
-    /**
-     * 检查是否已销毁
-     */
-    private checkDisposed;
-    private createGetters;
-    private createActions;
-}
-//# sourceMappingURL=base-store.d.ts.map

package/lib/core/batch-manager.d.ts

@@ -1,46 +0,0 @@
-/**
- * 批量更新管理器
- *
- * 用于优化多个状态更新的性能
- * @module core/batch-manager
- */
-import type { BatchManager, StoreId } from '../types';
-/**
- * 创建批量更新管理器
- *
- * @param onFlush - 刷新回调，接收所有待更新的 Store ID
- * @returns 批量更新管理器实例
- *
- * @example
- * ```typescript
- * const batchManager = createBatchManager((storeIds) => {
- *   storeIds.forEach(id => {
- *     // 通知订阅者更新
- *     notifySubscribers(id)
- *   })
- * })
- *
- * // 批量更新
- * batchManager.batch(() => {
- *   store1.count++
- *   store2.name = 'new name'
- * })
- * ```
- */
-export declare function createBatchManager(onFlush?: (storeIds: Set<StoreId>) => void): BatchManager;
-/**
- * 获取全局批量更新管理器
- */
-export declare function getGlobalBatchManager(): BatchManager;
-/**
- * 设置全局批量更新管理器
- */
-export declare function setGlobalBatchManager(manager: BatchManager): void;
-/**
- * 批量更新辅助函数
- *
- * @param fn - 执行函数
- * @returns 执行结果
- */
-export declare function batch<T>(fn: () => T): T;
-//# sourceMappingURL=batch-manager.d.ts.map

package/lib/core/index.d.ts

@@ -1,14 +0,0 @@
-/**
- * 核心模块导出
- *
- * @module core
- */
-export { createAsyncAction } from './async-action';
-export type { AsyncAction, AsyncActionOptions, AsyncActionState } from './async-action';
-export { BaseStore } from './base-store';
-export { batch, createBatchManager, getGlobalBatchManager, setGlobalBatchManager, } from './batch-manager';
-export { createStore } from './create-store';
-export type { CreateStoreDefinition, StoreAPI } from './create-store';
-export { createEventBus, globalEventBus } from './event-bus';
-export { createPubSub, createPubSubWithValue } from './pub-sub';
-//# sourceMappingURL=index.d.ts.map

package/lib/engine/index.d.ts

@@ -1,10 +0,0 @@
-/**
- * @module store/engine
- *
- * Store 引擎桥接层的统一导出，提供将 Store 能力集成到 LDesign Engine 的工厂函数、
- * 事件键和状态键。包含引擎 API、容器、事件总线等兼容接口类型，
- * 供 Vue/React 等适配层复用。
- */
-export { createStoreEngineBridge, storeEventKeys, storeStateKeys, } from './plugin';
-export type { StoreEngineApi, StoreEngineApiLike, StoreEngineBridge, StoreEngineBridgeOptions, StoreEngineContainerLike, StoreEngineEventsLike, StoreEngineLike, StoreEngineLoggerLike, StoreEnginePluginContextLike, StoreEnginePluginOptions, StoreEngineRegisteredApi, StoreEngineStateLike, StoreRuntimeLike, } from './types';
-//# sourceMappingURL=index.d.ts.map

package/lib/engine/plugin.d.ts

@@ -1,20 +0,0 @@
-/**
- * @composy/store-core Engine 桥接能力
- *
- * Core 负责 engine 生命周期、state/API 同步和事件派发；框架适配层只提供 runtime 创建与 App 挂载。
- * @module engine/plugin
- */
-import type { StoreEngineBridge, StoreEngineBridgeOptions, StoreRuntimeLike } from './types';
-export declare const storeStateKeys: {
-    readonly BUS: "store:bus";
-    readonly PINIA: "store:pinia";
-    readonly API: "store:api";
-    readonly REGISTRY: "store:registry";
-    readonly RUNTIME: "store:runtime";
-};
-export declare const storeEventKeys: {
-    readonly INSTALLED: "store:installed";
-    readonly UNINSTALLED: "store:uninstalled";
-};
-export declare function createStoreEngineBridge<Runtime extends StoreRuntimeLike>(options: StoreEngineBridgeOptions<Runtime>): StoreEngineBridge;
-//# sourceMappingURL=plugin.d.ts.map

package/lib/middleware/persist.d.ts

@@ -1,34 +0,0 @@
-/**
- * 持久化中间件
- *
- * 提供状态持久化功能
- * @module middleware/persist
- */
-import type { Middleware, PersistMiddlewareOptions, StateTree, StoreId } from '../types';
-/**
- * 创建持久化中间件
- *
- * @param options - 持久化选项
- * @returns 持久化中间件
- *
- * @example
- * ```typescript
- * const persist = createPersistMiddleware({
- *   storage: 'localStorage',
- *   stores: ['user', 'settings'],
- *   debounce: 200,
- * })
- *
- * middlewareManager.use(persist)
- * ```
- */
-export declare function createPersistMiddleware(options?: PersistMiddlewareOptions): Middleware;
-/**
- * 从存储恢复状态
- *
- * @param storeId - Store ID
- * @param options - 持久化选项
- * @returns 恢复的状态或 null
- */
-export declare function restoreState<S extends StateTree>(storeId: StoreId, options?: PersistMiddlewareOptions): S | null;
-//# sourceMappingURL=persist.d.ts.map