@free-walk/svelte-store 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 free-walk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# svelte-store
+
+Pinia 风格的 Svelte 5 状态管理库，基于 `svelte/store` 构建。
+
+## 特性
+
+- 🏪 **Pinia 风格 API** — `defineStore` 定义 store，支持 Options API 和 Setup 风格
+- 📦 **基于 svelte/store** — 完全兼容 Svelte 生态，支持 `$store` 自动订阅
+- 🔌 **插件系统** — 支持全局插件，可扩展持久化、日志等功能
+- 🎯 **TypeScript** — 完整类型推导
+- ⚡ **轻量** — 零额外依赖，仅依赖 `svelte/store`
+
+## 安装
+
+```bash
+npm install svelte-store
+```
+
+## 快速开始
+
+### Options API 风格
+
+```ts
+import { defineStore } from 'svelte-store'
+
+export const useCounterStore = defineStore('counter', {
+  state: () => ({
+    count: 0,
+    name: 'Counter',
+  }),
+  getters: {
+    doubleCount: (state) => state.count * 2,
+    displayName: (state) => `${state.name}: ${state.count}`,
+  },
+  actions: {
+    increment() {
+      this.$patch({ count: this.$state.count + 1 })
+    },
+    decrement() {
+      this.$patch({ count: this.$state.count - 1 })
+    },
+    incrementBy(amount: number) {
+      this.$patch({ count: this.$state.count + amount })
+    },
+  },
+})
+```
+
+### Setup 风格
+
+```ts
+import { defineStore, writable, derived } from 'svelte-store'
+
+export const useCounterStore = defineStore('counter', () => {
+  const count = writable(0)
+  const doubleCount = derived(count, ($count) => $count * 2)
+
+  function increment() {
+    count.update((n) => n + 1)
+  }
+
+  function decrement() {
+    count.update((n) => n - 1)
+  }
+
+  return { count, doubleCount, increment, decrement }
+})
+```
+
+### 在组件中使用
+
+```svelte
+<script>
+  import { useCounterStore } from '../stores/counter'
+
+  const counter = useCounterStore()
+</script>
+
+<p>Count: {counter.$state.count}</p>
+<p>Double: {counter.doubleCount}</p>
+
+<button onclick={() => counter.increment()}>+</button>
+<button onclick={() => counter.decrement()}>-</button>
+```
+
+## Store 实例 API
+
+| 方法 / 属性 | 说明 |
+|---|---|
+| `$id` | Store 的唯一标识字符串 |
+| `$state` | 获取当前 state 快照 |
+| `$patch(partial)` | 批量更新 state（对象或函数） |
+| `$reset()` | 重置 state 到初始值（仅 Options API） |
+| `$subscribe(callback)` | 监听 state 变化，返回取消订阅函数 |
+| `subscribe(run)` | svelte/store 标准订阅接口 |
+
+### $patch 用法
+
+```ts
+// 对象方式
+counter.$patch({ count: 10 })
+
+// 函数方式
+counter.$patch((state) => {
+  state.count++
+  state.name = 'Updated'
+})
+```
+
+### $subscribe 用法
+
+```ts
+const unsubscribe = counter.$subscribe((state) => {
+  console.log('state 变化:', state)
+})
+
+// 需要时取消订阅
+unsubscribe()
+```
+
+## 插件系统
+
+```ts
+import { addPlugin } from 'svelte-store'
+
+// 持久化插件示例
+addPlugin(({ store, storeId }) => {
+  // 恢复持久化数据
+  const key = `svelte-store-${storeId}`
+  const saved = localStorage.getItem(key)
+  if (saved) {
+    try {
+      store.$patch(JSON.parse(saved))
+    } catch {}
+  }
+
+  // 监听变化并持久化
+  store.$subscribe((state) => {
+    localStorage.setItem(key, JSON.stringify(state))
+  })
+})
+
+// 日志插件示例
+addPlugin(({ store, storeId }) => {
+  store.$subscribe((state) => {
+    console.log(`[${storeId}]`, state)
+  })
+})
+```
+
+## 辅助函数
+
+### mapState
+
+从 store 中提取状态为独立的 Readable store：
+
+```ts
+import { mapState } from 'svelte-store'
+
+const { count, name } = mapState(useCounterStore, ['count', 'name'])
+// count 和 name 是 Readable<number> 和 Readable<string>
+```
+
+### mapActions
+
+从 store 中提取 actions 为独立函数：
+
+```ts
+import { mapActions } from 'svelte-store'
+
+const { increment, decrement } = mapActions(useCounterStore, ['increment', 'decrement'])
+increment() // 直接调用
+```
+
+## 兼容性
+
+| 格式 | 文件 | 用途 |
+|---|---|---|
+| ESM | `dist/svelte-store.mjs` | `import` 语法 |
+| CJS | `dist/svelte-store.cjs` | `require()` 语法 |
+| Svelte 源码 | `src/index.ts` | Svelte 项目直接引用 |
+
+## License
+
+MIT

package/dist/svelte-store.cjs

@@ -0,0 +1 @@
+var l=Object.defineProperty;var R=Object.getOwnPropertyDescriptor;var v=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var j=(t,e)=>{for(var a in e)l(t,a,{get:e[a],enumerable:!0})},$=(t,e,a,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of v(e))!k.call(t,n)&&n!==a&&l(t,n,{get:()=>e[n],enumerable:!(r=R(e,n))||r.enumerable});return t};var O=t=>$(l({},"__esModule",{value:!0}),t);var W={};j(W,{addPlugin:()=>P,clearStores:()=>h,defineStore:()=>A,derived:()=>u.derived,get:()=>u.get,getRegisteredStore:()=>m,mapActions:()=>K,mapState:()=>D,readable:()=>u.readable,readonly:()=>u.readonly,writable:()=>u.writable});module.exports=O(W);var c=require("svelte/store"),u=require("svelte/store"),b=new Map,x=[];function A(t,e){return function(){if(b.has(t))return b.get(t);let r;typeof e=="function"?r=I(t,e):r=G(t,e),b.set(t,r);for(let n of x){let i=n({store:r,storeId:t,options:typeof e=="function"?{id:t}:e});i&&Object.assign(r,i)}return r}}function G(t,e){let a=e.state?e.state():{},r=(0,c.writable)({...a}),n={$id:t,subscribe:r.subscribe,get $state(){return(0,c.get)(r)},$patch(i){r.update(y=>typeof i=="function"?(i(y),{...y}):{...y,...i})},$reset(){let i=e.state?e.state():{};r.set({...i})},$subscribe(i){return r.subscribe(i)}};if(e.getters)for(let[i,y]of Object.entries(e.getters))Object.defineProperty(n,i,{get(){return y((0,c.get)(r))},enumerable:!0});if(e.actions)for(let[i,y]of Object.entries(e.actions))n[i]=(...d)=>y.apply(n,d);return n}function I(t,e){let a=e(),r=(0,c.writable)({}),n={},i={},y={};for(let[o,s]of Object.entries(a))typeof s=="function"?y[o]=s:s&&typeof s=="object"&&"subscribe"in s&&("set"in s?n[o]=s:i[o]=s);function d(){let o={};for(let[s,f]of Object.entries(n))o[s]=(0,c.get)(f);for(let[s,f]of Object.entries(i))o[s]=(0,c.get)(f);r.set(o)}let p=[];for(let o of Object.values(n))p.push(o.subscribe(()=>d()));for(let o of Object.values(i))p.push(o.subscribe(()=>d()));let g={$id:t,subscribe:r.subscribe,get $state(){return(0,c.get)(r)},$patch(o){if(typeof o=="function"){let s={};for(let[f,S]of Object.entries(n))s[f]=(0,c.get)(S);o(s);for(let[f,S]of Object.entries(n))f in s&&S.set(s[f])}else for(let[s,f]of Object.entries(o))s in n&&n[s].set(f)},$reset(){console.warn(`[svelte-store] Setup store "${t}" \u4E0D\u652F\u6301 $reset\uFF0C\u8BF7\u624B\u52A8\u91CD\u7F6E\u72B6\u6001`)},$subscribe(o){return r.subscribe(o)}};for(let[o,s]of Object.entries(y))g[o]=s;for(let[o,s]of Object.entries(n))Object.defineProperty(g,o,{get(){return(0,c.get)(s)},set(f){s.set(f)},enumerable:!0});for(let[o,s]of Object.entries(i))Object.defineProperty(g,o,{get(){return(0,c.get)(s)},enumerable:!0});return g}function P(t){x.push(t)}function m(t){return b.get(t)}function h(){b.clear()}function D(t,e){let a=t(),r={};for(let n of e)r[n]=(0,c.derived)({subscribe:a.subscribe},i=>i[n]);return r}function K(t,e){let a=t(),r={};for(let n of e)typeof a[n]=="function"&&(r[n]=a[n].bind(a));return r}

package/dist/svelte-store.mjs

@@ -0,0 +1 @@
+import{writable as l,derived as x,get as y}from"svelte/store";import{writable as D,readable as K,derived as W,get as F,readonly as w}from"svelte/store";var u=new Map,p=[];function $(o,i){return function(){if(u.has(o))return u.get(o);let t;typeof i=="function"?t=v(o,i):t=R(o,i),u.set(o,t);for(let r of p){let s=r({store:t,storeId:o,options:typeof i=="function"?{id:o}:i});s&&Object.assign(t,s)}return t}}function R(o,i){let c=i.state?i.state():{},t=l({...c}),r={$id:o,subscribe:t.subscribe,get $state(){return y(t)},$patch(s){t.update(f=>typeof s=="function"?(s(f),{...f}):{...f,...s})},$reset(){let s=i.state?i.state():{};t.set({...s})},$subscribe(s){return t.subscribe(s)}};if(i.getters)for(let[s,f]of Object.entries(i.getters))Object.defineProperty(r,s,{get(){return f(y(t))},enumerable:!0});if(i.actions)for(let[s,f]of Object.entries(i.actions))r[s]=(...b)=>f.apply(r,b);return r}function v(o,i){let c=i(),t=l({}),r={},s={},f={};for(let[n,e]of Object.entries(c))typeof e=="function"?f[n]=e:e&&typeof e=="object"&&"subscribe"in e&&("set"in e?r[n]=e:s[n]=e);function b(){let n={};for(let[e,a]of Object.entries(r))n[e]=y(a);for(let[e,a]of Object.entries(s))n[e]=y(a);t.set(n)}let S=[];for(let n of Object.values(r))S.push(n.subscribe(()=>b()));for(let n of Object.values(s))S.push(n.subscribe(()=>b()));let d={$id:o,subscribe:t.subscribe,get $state(){return y(t)},$patch(n){if(typeof n=="function"){let e={};for(let[a,g]of Object.entries(r))e[a]=y(g);n(e);for(let[a,g]of Object.entries(r))a in e&&g.set(e[a])}else for(let[e,a]of Object.entries(n))e in r&&r[e].set(a)},$reset(){console.warn(`[svelte-store] Setup store "${o}" \u4E0D\u652F\u6301 $reset\uFF0C\u8BF7\u624B\u52A8\u91CD\u7F6E\u72B6\u6001`)},$subscribe(n){return t.subscribe(n)}};for(let[n,e]of Object.entries(f))d[n]=e;for(let[n,e]of Object.entries(r))Object.defineProperty(d,n,{get(){return y(e)},set(a){e.set(a)},enumerable:!0});for(let[n,e]of Object.entries(s))Object.defineProperty(d,n,{get(){return y(e)},enumerable:!0});return d}function O(o){p.push(o)}function A(o){return u.get(o)}function G(){u.clear()}function I(o,i){let c=o(),t={};for(let r of i)t[r]=x({subscribe:c.subscribe},s=>s[r]);return t}function P(o,i){let c=o(),t={};for(let r of i)typeof c[r]=="function"&&(t[r]=c[r].bind(c));return t}export{O as addPlugin,G as clearStores,$ as defineStore,W as derived,F as get,A as getRegisteredStore,P as mapActions,I as mapState,K as readable,w as readonly,D as writable};

package/package.json

@@ -0,0 +1,45 @@
+{
+    "name": "@free-walk/svelte-store",
+    "version": "1.0.0",
+    "type": "module",
+    "description": "Pinia 风格的 Svelte 5 状态管理库，基于 svelte/store 构建",
+    "keywords": [
+        "svelte",
+        "svelte5",
+        "store",
+        "state-management",
+        "pinia"
+    ],
+    "license": "MIT",
+    "author": "free-walk",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/webcodingnpc/svelte-store.git"
+    },
+    "svelte": "./src/index.ts",
+    "main": "./dist/svelte-store.cjs",
+    "module": "./dist/svelte-store.mjs",
+    "exports": {
+        ".": {
+            "svelte": "./src/index.ts",
+            "import": "./dist/svelte-store.mjs",
+            "require": "./dist/svelte-store.cjs",
+            "default": "./dist/svelte-store.mjs"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "node scripts/build.js"
+    },
+    "peerDependencies": {
+        "svelte": "^5.0.0"
+    },
+    "devDependencies": {
+        "esbuild": "^0.27.7",
+        "svelte": "^5.55.1"
+    }
+}

package/src/index.ts

@@ -0,0 +1,434 @@
+/**
+ * svelte-store — Pinia 风格的 Svelte 5 状态管理库
+ *
+ * 核心概念：
+ * - defineStore：定义一个 store（类似 Pinia 的 defineStore）
+ * - state：响应式数据
+ * - getters：派生计算属性
+ * - actions：修改 state 的方法
+ * - plugins：全局插件系统
+ * - $subscribe：监听 state 变化
+ * - $patch：批量更新 state
+ * - $reset：重置 state 到初始值
+ */
+
+import { writable, derived, get, readonly } from 'svelte/store'
+import type { Writable, Readable, Unsubscriber } from 'svelte/store'
+
+// ==================== 类型定义 ====================
+
+/** Store 的 state 工厂函数 */
+export type StateFactory<S> = () => S
+
+/** Store 的 getters 定义 */
+export type GettersDefinition<S, G> = {
+    [K in keyof G]: (state: S) => G[K]
+}
+
+/** Store 的 actions 定义 */
+export type ActionsDefinition<S, A> = {
+    [K in keyof A]: A[K] extends (...args: infer P) => infer R
+    ? (this: StoreInstance<S, any, A>, ...args: P) => R
+    : never
+}
+
+/** Store Options API 风格定义 */
+export interface StoreOptionsDefinition<
+    Id extends string,
+    S extends Record<string, any>,
+    G extends Record<string, any>,
+    A extends Record<string, (...args: any[]) => any>,
+> {
+    id?: Id
+    state?: StateFactory<S>
+    getters?: GettersDefinition<S, G>
+    actions?: A
+}
+
+/** Setup 风格返回值 */
+export type SetupReturn = Record<string, any>
+
+/** Store 实例 */
+export interface StoreInstance<
+    S extends Record<string, any>,
+    G extends Record<string, any>,
+    A extends Record<string, (...args: any[]) => any>,
+> {
+    /** Store 唯一标识 */
+    $id: string
+    /** 订阅 state 变化 */
+    $subscribe: (callback: (state: S) => void) => Unsubscriber
+    /** 批量更新 state */
+    $patch: (partialOrUpdater: Partial<S> | ((state: S) => void)) => void
+    /** 重置 state 到初始值 */
+    $reset: () => void
+    /** 获取当前 state 快照 */
+    $state: S
+    /** svelte/store 订阅接口 */
+    subscribe: (run: (value: S) => void) => Unsubscriber
+}
+
+/** 插件上下文 */
+export interface PluginContext<S = any> {
+    store: StoreInstance<S, any, any>
+    storeId: string
+    options: StoreOptionsDefinition<string, S, any, any>
+}
+
+/** 插件类型 */
+export type StorePlugin = (context: PluginContext) => void | Record<string, any>
+
+// ==================== 全局状态 ====================
+
+/** 已注册的所有 store */
+const storeRegistry = new Map<string, any>()
+
+/** 已注册的插件 */
+const plugins: StorePlugin[] = []
+
+// ==================== 核心 API ====================
+
+/**
+ * 定义一个 Store（Options API 风格）
+ *
+ * @example
+ * ```ts
+ * const useCounterStore = defineStore('counter', {
+ *   state: () => ({ count: 0 }),
+ *   getters: {
+ *     double: (state) => state.count * 2,
+ *   },
+ *   actions: {
+ *     increment() { this.$patch({ count: this.$state.count + 1 }) },
+ *     decrement() { this.$patch({ count: this.$state.count - 1 }) },
+ *   },
+ * })
+ *
+ * // 在组件中使用
+ * const counter = useCounterStore()
+ * $: console.log($counter) // { count: 0 }
+ * counter.increment()
+ * ```
+ */
+export function defineStore<
+    Id extends string,
+    S extends Record<string, any> = {},
+    G extends Record<string, any> = {},
+    A extends Record<string, (...args: any[]) => any> = {},
+>(
+    id: Id,
+    options: StoreOptionsDefinition<Id, S, G, A>,
+): () => StoreInstance<S, G, A> & S & { [K in keyof G]: G[K] } & A
+
+/**
+ * 定义一个 Store（Setup 风格）
+ *
+ * @example
+ * ```ts
+ * const useCounterStore = defineStore('counter', () => {
+ *   let count = writable(0)
+ *   const double = derived(count, $c => $c * 2)
+ *   function increment() { count.update(n => n + 1) }
+ *   return { count, double, increment }
+ * })
+ * ```
+ */
+export function defineStore<Id extends string>(
+    id: Id,
+    setup: () => SetupReturn,
+): () => any
+
+export function defineStore(
+    id: string,
+    optionsOrSetup: StoreOptionsDefinition<string, any, any, any> | (() => SetupReturn),
+) {
+    return function useStore() {
+        // 单例：同一 id 只创建一次
+        if (storeRegistry.has(id)) {
+            return storeRegistry.get(id)
+        }
+
+        let store: any
+
+        if (typeof optionsOrSetup === 'function') {
+            // Setup 风格
+            store = createSetupStore(id, optionsOrSetup)
+        } else {
+            // Options API 风格
+            store = createOptionsStore(id, optionsOrSetup)
+        }
+
+        storeRegistry.set(id, store)
+
+        // 执行插件
+        for (const plugin of plugins) {
+            const extensions = plugin({
+                store,
+                storeId: id,
+                options: typeof optionsOrSetup === 'function' ? { id } : optionsOrSetup,
+            })
+            if (extensions) {
+                Object.assign(store, extensions)
+            }
+        }
+
+        return store
+    }
+}
+
+// ==================== Options Store 创建 ====================
+
+function createOptionsStore(
+    id: string,
+    options: StoreOptionsDefinition<string, any, any, any>,
+) {
+    const initialState = options.state ? options.state() : {}
+    const stateStore: Writable<any> = writable({ ...initialState })
+
+    // 构建 store 实例
+    const store: any = {
+        $id: id,
+        subscribe: stateStore.subscribe,
+
+        get $state() {
+            return get(stateStore)
+        },
+
+        $patch(partialOrUpdater: any) {
+            stateStore.update((current: any) => {
+                if (typeof partialOrUpdater === 'function') {
+                    partialOrUpdater(current)
+                    return { ...current }
+                }
+                return { ...current, ...partialOrUpdater }
+            })
+        },
+
+        $reset() {
+            const freshState = options.state ? options.state() : {}
+            stateStore.set({ ...freshState })
+        },
+
+        $subscribe(callback: (state: any) => void) {
+            return stateStore.subscribe(callback)
+        },
+    }
+
+    // 绑定 getters
+    if (options.getters) {
+        for (const [key, getter] of Object.entries(options.getters)) {
+            Object.defineProperty(store, key, {
+                get() {
+                    return (getter as Function)(get(stateStore))
+                },
+                enumerable: true,
+            })
+        }
+    }
+
+    // 绑定 actions（this 指向 store 实例）
+    if (options.actions) {
+        for (const [key, action] of Object.entries(options.actions)) {
+            store[key] = (...args: any[]) => (action as Function).apply(store, args)
+        }
+    }
+
+    return store
+}
+
+// ==================== Setup Store 创建 ====================
+
+function createSetupStore(id: string, setup: () => SetupReturn) {
+    const result = setup()
+    const stateStore: Writable<any> = writable({})
+
+    // 分离 stores、computed 和 actions
+    const storeEntries: Record<string, Writable<any>> = {}
+    const readableEntries: Record<string, Readable<any>> = {}
+    const actionEntries: Record<string, Function> = {}
+
+    for (const [key, value] of Object.entries(result)) {
+        if (typeof value === 'function') {
+            actionEntries[key] = value
+        } else if (value && typeof value === 'object' && 'subscribe' in value) {
+            if ('set' in value) {
+                storeEntries[key] = value as Writable<any>
+            } else {
+                readableEntries[key] = value as Readable<any>
+            }
+        }
+    }
+
+    // 同步 state snapshot
+    function syncState() {
+        const state: any = {}
+        for (const [key, s] of Object.entries(storeEntries)) {
+            state[key] = get(s)
+        }
+        for (const [key, s] of Object.entries(readableEntries)) {
+            state[key] = get(s)
+        }
+        stateStore.set(state)
+    }
+
+    // 订阅所有 writable stores 的变化
+    const unsubs: Unsubscriber[] = []
+    for (const s of Object.values(storeEntries)) {
+        unsubs.push(s.subscribe(() => syncState()))
+    }
+    for (const s of Object.values(readableEntries)) {
+        unsubs.push(s.subscribe(() => syncState()))
+    }
+
+    const store: any = {
+        $id: id,
+        subscribe: stateStore.subscribe,
+
+        get $state() {
+            return get(stateStore)
+        },
+
+        $patch(partialOrUpdater: any) {
+            if (typeof partialOrUpdater === 'function') {
+                const current: any = {}
+                for (const [key, s] of Object.entries(storeEntries)) {
+                    current[key] = get(s)
+                }
+                partialOrUpdater(current)
+                for (const [key, s] of Object.entries(storeEntries)) {
+                    if (key in current) s.set(current[key])
+                }
+            } else {
+                for (const [key, value] of Object.entries(partialOrUpdater)) {
+                    if (key in storeEntries) {
+                        storeEntries[key].set(value)
+                    }
+                }
+            }
+        },
+
+        $reset() {
+            // Setup store 没有初始工厂，不支持 $reset
+            console.warn(`[svelte-store] Setup store "${id}" 不支持 $reset，请手动重置状态`)
+        },
+
+        $subscribe(callback: (state: any) => void) {
+            return stateStore.subscribe(callback)
+        },
+    }
+
+    // 暴露 actions
+    for (const [key, action] of Object.entries(actionEntries)) {
+        store[key] = action
+    }
+
+    // 暴露 writable stores（通过 getter/setter 代理）
+    for (const [key, s] of Object.entries(storeEntries)) {
+        Object.defineProperty(store, key, {
+            get() { return get(s) },
+            set(value: any) { s.set(value) },
+            enumerable: true,
+        })
+    }
+
+    // 暴露 readable stores（通过 getter）
+    for (const [key, s] of Object.entries(readableEntries)) {
+        Object.defineProperty(store, key, {
+            get() { return get(s) },
+            enumerable: true,
+        })
+    }
+
+    return store
+}
+
+// ==================== 插件系统 ====================
+
+/**
+ * 注册全局插件
+ *
+ * @example
+ * ```ts
+ * import { addPlugin } from 'svelte-store'
+ *
+ * // 持久化插件
+ * addPlugin(({ store, storeId }) => {
+ *   const saved = localStorage.getItem(`store-${storeId}`)
+ *   if (saved) store.$patch(JSON.parse(saved))
+ *   store.$subscribe((state) => {
+ *     localStorage.setItem(`store-${storeId}`, JSON.stringify(state))
+ *   })
+ * })
+ * ```
+ */
+export function addPlugin(plugin: StorePlugin): void {
+    plugins.push(plugin)
+}
+
+// ==================== 工具函数 ====================
+
+/**
+ * 获取已注册的 store 实例（需先调用过 useStore）
+ */
+export function getRegisteredStore(id: string): any | undefined {
+    return storeRegistry.get(id)
+}
+
+/**
+ * 清除所有已注册的 store（测试用）
+ */
+export function clearStores(): void {
+    storeRegistry.clear()
+}
+
+/**
+ * 创建 store 映射辅助函数
+ * 类似 Pinia 的 mapState
+ *
+ * @example
+ * ```ts
+ * const useCounter = defineStore('counter', {
+ *   state: () => ({ count: 0, name: 'Counter' }),
+ * })
+ *
+ * // mapState 提取部分 state
+ * const { count, name } = mapState(useCounter, ['count', 'name'])
+ * ```
+ */
+export function mapState<S extends Record<string, any>>(
+    useStore: () => any,
+    keys: (keyof S)[],
+): Record<keyof S, Readable<any>> {
+    const store = useStore()
+    const result: any = {}
+    for (const key of keys) {
+        result[key] = derived({ subscribe: store.subscribe }, ($state: S) => $state[key])
+    }
+    return result
+}
+
+/**
+ * 转发 store 中的 actions
+ *
+ * @example
+ * ```ts
+ * const { increment, decrement } = mapActions(useCounter, ['increment', 'decrement'])
+ * ```
+ */
+export function mapActions(
+    useStore: () => any,
+    keys: string[],
+): Record<string, (...args: any[]) => any> {
+    const store = useStore()
+    const result: any = {}
+    for (const key of keys) {
+        if (typeof store[key] === 'function') {
+            result[key] = store[key].bind(store)
+        }
+    }
+    return result
+}
+
+// 重新导出 svelte/store 常用 API
+export { writable, readable, derived, get, readonly } from 'svelte/store'
+export type { Writable, Readable, Unsubscriber } from 'svelte/store'