@kaokei/use-vue-service 3.0.1 → 4.0.0

package/README.md

@@ -13,12 +13,19 @@
 
 灵感来自 angular 中的服务的概念。在 angular 中不需要全局唯一的数据源 store。而是通过声明服务，以及向组件中注入服务来达到数据管理以及数据共享的。
 
-本库也是实现了类似的效果，可以通过依赖注入实现面向服务编程、实现领域驱动开发。从而可以代替 vuex。
+本库也是实现了类似的效果，可以通过依赖注入实现面向服务编程、实现领域驱动开发。从而可以代替 vuex/pinia。
 
 本库通过类来声明服务，对 typescript 支持非常棒。
 
-- [入门指南](./docs/guide/README.md)
-- [API 文档](./docs/api/README.md)
+- [入门指南](./docs/guide/index.md)
+- [API 文档](./docs/api/index.md)
 - [博客文章](./docs/note/01.父组件与子组件的理解.md)
 - [codesandbox example](https://codesandbox.io/s/di-playground-zjnyv)
 - [online demo](https://use-vue-service.vercel.app/)
+
+## Todo List
+1. 优化@Computed
+5. 增加@Raw装饰器
+4. 更新hasOwn
+3. 发布@kaokei/di@5.0.3
+2. 评估是否需要@Watch/@Effect

package/dist/computed.d.cts

@@ -1 +1,2 @@
-export declare function Computed(_: any, key: string, descriptor: PropertyDescriptor): PropertyDescriptor;
+export declare function Computed(): (value: (this: any) => any, context: ClassGetterDecoratorContext) => (this: any) => any;
+export declare function Computed(value: (this: any) => any, context: ClassGetterDecoratorContext): (this: any) => any;

package/dist/computed.d.ts

@@ -1 +1,2 @@
-export declare function Computed(_: any, key: string, descriptor: PropertyDescriptor): PropertyDescriptor;
+export declare function Computed(): (value: (this: any) => any, context: ClassGetterDecoratorContext) => (this: any) => any;
+export declare function Computed(value: (this: any) => any, context: ClassGetterDecoratorContext): (this: any) => any;

package/dist/constants.d.cts

@@ -1,9 +1,7 @@
-import { Token } from '@kaokei/di';
-import { ComponentInternalInstance } from 'vue';
+import { Token, Container } from '@kaokei/di';
+import { InjectionKey } from 'vue';
 import { FindChildService, FindChildrenServices } from './interface.ts';
-export declare const CURRENT_COMPONENT: Token<ComponentInternalInstance>;
 export declare const FIND_CHILD_SERVICE: Token<FindChildService>;
 export declare const FIND_CHILDREN_SERVICES: Token<FindChildrenServices>;
 export declare const SCOPE_KEY: unique symbol;
-export declare const CONTAINER_TOKEN = "USE_VUE_SERVICE_CONTAINER_TOKEN";
-export declare const DEFAULT_CONTAINER: import('@kaokei/di').Container;
+export declare const CONTAINER_TOKEN: InjectionKey<Container>;

package/dist/constants.d.ts

@@ -1,9 +1,7 @@
-import { Token } from '@kaokei/di';
-import { ComponentInternalInstance } from 'vue';
+import { Token, Container } from '@kaokei/di';
+import { InjectionKey } from 'vue';
 import { FindChildService, FindChildrenServices } from './interface.ts';
-export declare const CURRENT_COMPONENT: Token<ComponentInternalInstance>;
 export declare const FIND_CHILD_SERVICE: Token<FindChildService>;
 export declare const FIND_CHILDREN_SERVICES: Token<FindChildrenServices>;
 export declare const SCOPE_KEY: unique symbol;
-export declare const CONTAINER_TOKEN = "USE_VUE_SERVICE_CONTAINER_TOKEN";
-export declare const DEFAULT_CONTAINER: import('@kaokei/di').Container;
+export declare const CONTAINER_TOKEN: InjectionKey<Container>;

package/dist/core.d.cts

@@ -1,14 +1,89 @@
 import { App } from 'vue';
 import { CommonToken } from '@kaokei/di';
 import { NewableProvider, FunctionProvider, Provider } from './interface.ts';
+/**
+ * 从当前组件或最近的祖先组件的 DI 容器中获取服务实例。
+ *
+ * 查找顺序：
+ * 1. 先检查当前组件自身是否声明了容器（getCurrentContainer）
+ * 2. 如果没有，则沿组件树向上查找（getProvideContainer）
+ *
+ * @param token - 服务的标识符，可以是类本身（Newable）或 Token 实例
+ * @returns 对应 token 的服务实例
+ */
 export declare function useService<T>(token: CommonToken<T>): T;
-export declare function useRootService<T>(token: CommonToken<T>): T;
-export declare function useAppService<T>(token: CommonToken<T>, app: App): T;
+/**
+ * 在当前组件中声明服务提供者。
+ *
+ * 行为逻辑：
+ * - 如果当前组件已经声明过容器（重复调用 declareProviders），则直接在已有容器上追加绑定。
+ * - 如果当前组件尚未声明容器，则：
+ *   1. 获取父级容器作为 parent
+ *   2. 创建一个子容器（继承父级容器的所有绑定）
+ *   3. 在子容器上绑定新的服务
+ *   4. 通过 Vue 的 provide 将子容器注入组件树
+ *   5. 在组件卸载时（onUnmounted）自动销毁子容器，清理资源
+ *
+ * @param providers - 服务提供者，支持类数组或函数两种形式
+ */
 export declare function declareProviders(providers: FunctionProvider): void;
 export declare function declareProviders(providers: NewableProvider): void;
+export declare function declareProviders(providers: Provider): void;
+/**
+ * 从全局根容器（ROOT_CONTAINER）中获取服务实例。
+ * 不依赖 Vue 组件树，可以在任何地方调用。
+ *
+ * @param token - 服务的标识符
+ * @returns 对应 token 的服务实例
+ */
+export declare function useRootService<T>(token: CommonToken<T>): T;
+/**
+ * 在全局根容器上声明服务提供者。
+ * 绑定的服务在整个应用中全局共享。
+ *
+ * @param providers - 服务提供者，支持类数组或函数两种形式
+ */
 export declare function declareRootProviders(providers: FunctionProvider): void;
 export declare function declareRootProviders(providers: NewableProvider): void;
+export declare function declareRootProviders(providers: Provider): void;
+/**
+ * 在指定 Vue App 实例的上下文中获取服务实例。
+ * 通过 app.runWithContext 确保 inject 能正确找到该 App 提供的容器。
+ * 适用于多 App 实例场景。
+ *
+ * @param token - 服务的标识符
+ * @param app - 目标 Vue App 实例
+ * @returns 对应 token 的服务实例
+ */
+export declare function useAppService<T>(token: CommonToken<T>, app: App): T;
+/**
+ * 在指定 Vue App 实例的上下文中声明服务提供者。
+ *
+ * 行为逻辑：
+ * - 如果该 App 已经有容器（之前调用过 declareAppProviders），则直接追加绑定。
+ * - 如果该 App 尚未有容器，则：
+ *   1. 以 ROOT_CONTAINER 为 parent 创建子容器
+ *   2. 绑定服务
+ *   3. 通过 app.provide 将容器注入该 App 的组件树
+ *   4. 在 App 卸载时自动销毁容器
+ *
+ * @param providers - 服务提供者，支持类数组或函数两种形式
+ * @param app - 目标 Vue App 实例
+ */
 export declare function declareAppProviders(providers: FunctionProvider, app: App): void;
 export declare function declareAppProviders(providers: NewableProvider, app: App): void;
 export declare function declareAppProviders(providers: Provider, app: App): void;
+/**
+ * declareAppProviders 的 Vue 插件形式。
+ * 返回一个符合 Vue 插件接口的函数，可直接用于 app.use()。
+ *
+ * @example
+ * ```ts
+ * const app = createApp(App);
+ * app.use(declareAppProvidersPlugin([ServiceA, ServiceB]));
+ * ```
+ *
+ * @param providers - 服务提供者
+ * @returns Vue 插件函数
+ */
 export declare function declareAppProvidersPlugin(providers: Provider): (app: App) => void;

package/dist/core.d.ts

@@ -1,14 +1,89 @@
 import { App } from 'vue';
 import { CommonToken } from '@kaokei/di';
 import { NewableProvider, FunctionProvider, Provider } from './interface.ts';
+/**
+ * 从当前组件或最近的祖先组件的 DI 容器中获取服务实例。
+ *
+ * 查找顺序：
+ * 1. 先检查当前组件自身是否声明了容器（getCurrentContainer）
+ * 2. 如果没有，则沿组件树向上查找（getProvideContainer）
+ *
+ * @param token - 服务的标识符，可以是类本身（Newable）或 Token 实例
+ * @returns 对应 token 的服务实例
+ */
 export declare function useService<T>(token: CommonToken<T>): T;
-export declare function useRootService<T>(token: CommonToken<T>): T;
-export declare function useAppService<T>(token: CommonToken<T>, app: App): T;
+/**
+ * 在当前组件中声明服务提供者。
+ *
+ * 行为逻辑：
+ * - 如果当前组件已经声明过容器（重复调用 declareProviders），则直接在已有容器上追加绑定。
+ * - 如果当前组件尚未声明容器，则：
+ *   1. 获取父级容器作为 parent
+ *   2. 创建一个子容器（继承父级容器的所有绑定）
+ *   3. 在子容器上绑定新的服务
+ *   4. 通过 Vue 的 provide 将子容器注入组件树
+ *   5. 在组件卸载时（onUnmounted）自动销毁子容器，清理资源
+ *
+ * @param providers - 服务提供者，支持类数组或函数两种形式
+ */
 export declare function declareProviders(providers: FunctionProvider): void;
 export declare function declareProviders(providers: NewableProvider): void;
+export declare function declareProviders(providers: Provider): void;
+/**
+ * 从全局根容器（ROOT_CONTAINER）中获取服务实例。
+ * 不依赖 Vue 组件树，可以在任何地方调用。
+ *
+ * @param token - 服务的标识符
+ * @returns 对应 token 的服务实例
+ */
+export declare function useRootService<T>(token: CommonToken<T>): T;
+/**
+ * 在全局根容器上声明服务提供者。
+ * 绑定的服务在整个应用中全局共享。
+ *
+ * @param providers - 服务提供者，支持类数组或函数两种形式
+ */
 export declare function declareRootProviders(providers: FunctionProvider): void;
 export declare function declareRootProviders(providers: NewableProvider): void;
+export declare function declareRootProviders(providers: Provider): void;
+/**
+ * 在指定 Vue App 实例的上下文中获取服务实例。
+ * 通过 app.runWithContext 确保 inject 能正确找到该 App 提供的容器。
+ * 适用于多 App 实例场景。
+ *
+ * @param token - 服务的标识符
+ * @param app - 目标 Vue App 实例
+ * @returns 对应 token 的服务实例
+ */
+export declare function useAppService<T>(token: CommonToken<T>, app: App): T;
+/**
+ * 在指定 Vue App 实例的上下文中声明服务提供者。
+ *
+ * 行为逻辑：
+ * - 如果该 App 已经有容器（之前调用过 declareAppProviders），则直接追加绑定。
+ * - 如果该 App 尚未有容器，则：
+ *   1. 以 ROOT_CONTAINER 为 parent 创建子容器
+ *   2. 绑定服务
+ *   3. 通过 app.provide 将容器注入该 App 的组件树
+ *   4. 在 App 卸载时自动销毁容器
+ *
+ * @param providers - 服务提供者，支持类数组或函数两种形式
+ * @param app - 目标 Vue App 实例
+ */
 export declare function declareAppProviders(providers: FunctionProvider, app: App): void;
 export declare function declareAppProviders(providers: NewableProvider, app: App): void;
 export declare function declareAppProviders(providers: Provider, app: App): void;
+/**
+ * declareAppProviders 的 Vue 插件形式。
+ * 返回一个符合 Vue 插件接口的函数，可直接用于 app.use()。
+ *
+ * @example
+ * ```ts
+ * const app = createApp(App);
+ * app.use(declareAppProvidersPlugin([ServiceA, ServiceB]));
+ * ```
+ *
+ * @param providers - 服务提供者
+ * @returns Vue 插件函数
+ */
 export declare function declareAppProvidersPlugin(providers: Provider): (app: App) => void;

package/dist/create-container.d.cts

@@ -0,0 +1,2 @@
+import { Container } from '@kaokei/di';
+export declare function createContainer(parent?: Container): Container;

package/dist/create-container.d.ts

@@ -0,0 +1,2 @@
+import { Container } from '@kaokei/di';
+export declare function createContainer(parent?: Container): Container;

package/dist/effect-scope.d.cts

@@ -0,0 +1,41 @@
+import { EffectScope } from 'vue';
+/**
+ * 被装饰方法的类型约束：
+ * - 方法体内应返回 void（装饰器会接管返回值）
+ * - 但方法签名可以声明返回 EffectScope，以便调用侧获得正确的类型推断
+ *
+ * 已知限制：
+ * TypeScript 装饰器目前无法自动修改被装饰方法的返回类型。
+ * 原始方法返回 void，但装饰器在运行时将返回值替换为 EffectScope。
+ * 因此调用侧默认推断为 void，无法直接访问 EffectScope 的属性（如 stop()）。
+ *
+ * 方案 1（推荐）：在调用侧强制类型转换
+ * 实际业务中通常只需要调用 stop() 方法来清理副作用，直接在调用侧做类型断言即可：
+ * ```ts
+ * const scope = reactiveDemo.setup() as any;
+ * scope.stop();
+ * // 或者更精确的类型转换：
+ * const scope = reactiveDemo.setup() as unknown as EffectScope;
+ * scope.stop();
+ * ```
+ *
+ * 方案 2：显式声明方法返回类型 + return 占位
+ * 在被装饰方法上声明返回 EffectScope，并在方法体末尾添加占位 return，
+ * 这样调用侧可以直接获得正确的类型推断：
+ * ```ts
+ * import type { EffectScope } from 'vue';
+ *
+ * class DemoService {
+ *   @RunInScope
+ *   public setup(): EffectScope {
+ *     watchEffect(() => { ... });
+ *     return null as any;
+ *     // 或者：return null as unknown as EffectScope;
+ *   }
+ * }
+ * ```
+ */
+type DecorableMethod = (this: any, ...args: any[]) => void | EffectScope;
+export declare function RunInScope(): (value: DecorableMethod, context: ClassMethodDecoratorContext) => (this: any, ...args: any[]) => EffectScope;
+export declare function RunInScope(value: DecorableMethod, context: ClassMethodDecoratorContext): (this: any, ...args: any[]) => EffectScope;
+export {};

package/dist/effect-scope.d.ts

@@ -0,0 +1,41 @@
+import { EffectScope } from 'vue';
+/**
+ * 被装饰方法的类型约束：
+ * - 方法体内应返回 void（装饰器会接管返回值）
+ * - 但方法签名可以声明返回 EffectScope，以便调用侧获得正确的类型推断
+ *
+ * 已知限制：
+ * TypeScript 装饰器目前无法自动修改被装饰方法的返回类型。
+ * 原始方法返回 void，但装饰器在运行时将返回值替换为 EffectScope。
+ * 因此调用侧默认推断为 void，无法直接访问 EffectScope 的属性（如 stop()）。
+ *
+ * 方案 1（推荐）：在调用侧强制类型转换
+ * 实际业务中通常只需要调用 stop() 方法来清理副作用，直接在调用侧做类型断言即可：
+ * ```ts
+ * const scope = reactiveDemo.setup() as any;
+ * scope.stop();
+ * // 或者更精确的类型转换：
+ * const scope = reactiveDemo.setup() as unknown as EffectScope;
+ * scope.stop();
+ * ```
+ *
+ * 方案 2：显式声明方法返回类型 + return 占位
+ * 在被装饰方法上声明返回 EffectScope，并在方法体末尾添加占位 return，
+ * 这样调用侧可以直接获得正确的类型推断：
+ * ```ts
+ * import type { EffectScope } from 'vue';
+ *
+ * class DemoService {
+ *   @RunInScope
+ *   public setup(): EffectScope {
+ *     watchEffect(() => { ... });
+ *     return null as any;
+ *     // 或者：return null as unknown as EffectScope;
+ *   }
+ * }
+ * ```
+ */
+type DecorableMethod = (this: any, ...args: any[]) => void | EffectScope;
+export declare function RunInScope(): (value: DecorableMethod, context: ClassMethodDecoratorContext) => (this: any, ...args: any[]) => EffectScope;
+export declare function RunInScope(value: DecorableMethod, context: ClassMethodDecoratorContext): (this: any, ...args: any[]) => EffectScope;
+export {};

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("@kaokei/di"),r=require("vue");function E(e,t,n){return e&&e.forEach(o=>{o&&o.isCurrentBound(t)&&n.push(o.get(t)),o.children&&E(o.children,t,n)}),n}function y(e,t){const n=[];return E(t.children,e,n),n[0]}function b(e,t){const n=[];return E(t.children,e,n),n}function T(e){const t=e,n=r.effectScope(!0);return t[S]=n,n}function R(e){return e[S]}function _(e){const t=R(e);return t||T(e)}function D(e){const t=e;if(t){const n=R(t);n&&(n.stop(),delete t[S])}}function V(e){return e!==null&&typeof e=="object"}function A(e,t){return V(t)?r.reactive(t):t}function U(e){return D(e)}function w({container:e}){return t=>y(t,e)}function j({container:e}){return t=>b(t,e)}function p(e,t){let n;return e?n=e.createChild():n=new s.Container,t&&n.bind(I).toConstantValue(r.markRaw(t)),n.bind(h).toDynamicValue(w),n.bind(N).toDynamicValue(j),n.onActivation(A),n.onDeactivation(U),n}const I=new s.Token("USE_VUE_SERVICE_CURRENT_COMPONENT"),h=new s.Token("USE_REACT_SERVICE_FIND_CHILD_SERVICE"),N=new s.Token("USE_REACT_SERVICE_FIND_CHILDREN_SERVICES"),S=Symbol(),a="USE_VUE_SERVICE_CONTAINER_TOKEN",d=p();function l(e,t){if(typeof t=="function")t(e);else for(let n=0;n<t.length;n++)e.bind(t[n]).toSelf()}function g(){const e=r.getCurrentInstance();if(e){const t=a,n=e.provides,o=e.parent&&e.parent.provides;if(n&&n!==o&&Object.prototype.hasOwnProperty.call(n,t))return n[t]}}function v(){if(r.hasInjectionContext())return r.inject(a,d);throw new Error("getProvideContainer 只能在 setup 中使用")}function F(e){return(g()||v()).get(e)}function H(e){return d.get(e)}function L(e,t){return t.runWithContext(()=>v().get(e))}function M(e){const t=g();if(t)l(t,e);else{const n=v(),o=r.getCurrentInstance();let c=p(n,o);l(c,e),r.provide(a,c),r.onUnmounted(()=>{c.destroy(),c=null})}}function x(e){l(d,e)}function m(e,t){t.runWithContext(()=>{const n=r.inject(a,null);if(n)l(n,e);else{let o=p(d);l(o,e),t.provide(a,o),t.onUnmount(()=>{o.destroy(),o=null})}})}function K(e){return t=>m(e,t)}function k(e,t,n){const o=n.get,c=n.set;return{configurable:!0,enumerable:!0,get(){const i=r.reactive(this),f=Symbol.for(t);let u=i[f];if(!u){const O=_(i).run(()=>c?r.computed({get:()=>o.call(i),set:P=>c.call(i,P)}):r.computed(()=>o.call(i)));u=r.markRaw({value:O}),i[f]=u}return u.value.value},set(i){const f=r.reactive(this),u=Symbol.for(t),C=f[u];C&&c&&(C.value.value=i)}}}exports.CURRENT_COMPONENT=I;exports.Computed=k;exports.FIND_CHILDREN_SERVICES=N;exports.FIND_CHILD_SERVICE=h;exports.declareAppProviders=m;exports.declareAppProvidersPlugin=K;exports.declareProviders=M;exports.declareRootProviders=x;exports.getEffectScope=_;exports.useAppService=L;exports.useRootService=H;exports.useService=F;Object.keys(s).forEach(e=>{e!=="default"&&!Object.prototype.hasOwnProperty.call(exports,e)&&Object.defineProperty(exports,e,{enumerable:!0,get:()=>s[e]})});
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("@kaokei/di"),o=require("vue"),P=new c.Token("FIND_CHILD_SERVICE"),m=new c.Token("FIND_CHILDREN_SERVICES"),C=Symbol("SCOPE_KEY"),s=Symbol("CONTAINER_TOKEN");function w(t){const e=t,n=o.effectScope(!0);return e[C]=n,n}function b(t){return t[C]}function j(t){const e=t;if(e){const n=b(e);n&&(n.stop(),delete e[C])}}function D(t){const e=b(t);return e||w(t)}function h(t,e,n,r){if(t){for(const i of t)if(i.isCurrentBound(e)&&(n.push(i.get(e)),r)||i.children&&h(i.children,e,n,r))return!0}return!1}function A(t,e){const n=[];return h(e.children,t,n,!0),n[0]}function T(t,e){const n=[];return h(e.children,t,n,!1),n}function V(t,e){return c.isObject(e)?o.reactive(e):e}function H(t){return j(t)}function k({container:t}){return e=>A(e,t)}function F({container:t}){return e=>T(e,t)}function g(t){let e;return t?e=t.createChild():e=new c.Container,e.bind(P).toDynamicValue(k),e.bind(m).toDynamicValue(F),e.onActivation(V),e.onDeactivation(H),e}const d=g();function a(t,e){if(typeof e=="function")e(t);else for(let n=0;n<e.length;n++)t.bind(e[n]).toSelf()}function N(){const t=o.getCurrentInstance();if(t){const e=s,n=t.provides,r=t.parent&&t.parent.provides;if(n&&n!==r&&c.hasOwn(n,e))return n[e]}}function v(){if(o.hasInjectionContext())return o.inject(s,d);throw new Error("getProvideContainer 只能在 setup 中使用")}function L(t){return(N()||v()).get(t)}function K(t){const e=N();if(e)a(e,t);else{const n=v();let r=g(n);a(r,t),o.provide(s,r),o.onUnmounted(()=>{r.destroy(),r=null})}}function q(t){return d.get(t)}function U(t){a(d,t)}function W(t,e){return e.runWithContext(()=>v().get(t))}function _(t,e){e.runWithContext(()=>{const n=o.inject(s,null);if(n)a(n,t);else{let r=g(d);a(r,t),e.provide(s,r),e.onUnmount(()=>{r.destroy(),r=null})}})}function Y(t){return e=>_(t,e)}function O(t,e){const n=e.name;return function(){const r=D(this),i=t,E=o.toRaw(this);let p,f=Object.getPrototypeOf(E);for(;f;){const u=Object.getOwnPropertyDescriptor(f,n);if(u&&u.set){p=u.set;break}f=Object.getPrototypeOf(f)}const S=this,I=p?r.run(()=>o.computed({get:()=>i.call(S),set:u=>p.call(S,u)})):r.run(()=>o.computed(()=>i.call(S)));return Object.defineProperty(E,n,{value:I,writable:!0,configurable:!0,enumerable:!0}),I.value}}function z(t,e){return typeof t=="function"&&(e==null?void 0:e.kind)==="getter"?O(t,e):O}function l(t){return c.isObject(t)?o.markRaw(t):t}function R(t,e){if(e.kind==="accessor")return{get(){return t.get.call(this)},set(r){t.set.call(this,l(r))},init:l};const n=e.name;return e.addInitializer(function(){let r;Object.defineProperty(this,n,{configurable:!0,enumerable:!0,get(){return r},set(i){r=l(i)}})}),l}function B(t,e){return(e==null?void 0:e.kind)==="field"||(e==null?void 0:e.kind)==="accessor"?R(t,e):R}function y(t,e){return function(...n){const i=D(this).run(()=>o.effectScope());return i.run(()=>t.call(this,...n)),i}}function G(t,e){return typeof t=="function"&&(e==null?void 0:e.kind)==="method"?y(t):y}exports.Computed=z;exports.FIND_CHILDREN_SERVICES=m;exports.FIND_CHILD_SERVICE=P;exports.Raw=B;exports.RunInScope=G;exports.declareAppProviders=_;exports.declareAppProvidersPlugin=Y;exports.declareProviders=K;exports.declareRootProviders=U;exports.useAppService=W;exports.useRootService=q;exports.useService=L;Object.keys(c).forEach(t=>{t!=="default"&&!Object.prototype.hasOwnProperty.call(exports,t)&&Object.defineProperty(exports,t,{enumerable:!0,get:()=>c[t]})});

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 export * from '@kaokei/di';
-export { CURRENT_COMPONENT, FIND_CHILD_SERVICE, FIND_CHILDREN_SERVICES, } from './constants.ts';
 export { useService, declareProviders, useRootService, declareRootProviders, useAppService, declareAppProviders, declareAppProvidersPlugin, } from './core.ts';
+export { FIND_CHILD_SERVICE, FIND_CHILDREN_SERVICES } from './constants.ts';
 export { Computed } from './computed.ts';
-export { getEffectScope } from './scope.ts';
+export { Raw } from './raw.ts';
+export { RunInScope } from './effect-scope.ts';

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from '@kaokei/di';
-export { CURRENT_COMPONENT, FIND_CHILD_SERVICE, FIND_CHILDREN_SERVICES, } from './constants.ts';
 export { useService, declareProviders, useRootService, declareRootProviders, useAppService, declareAppProviders, declareAppProvidersPlugin, } from './core.ts';
+export { FIND_CHILD_SERVICE, FIND_CHILDREN_SERVICES } from './constants.ts';
 export { Computed } from './computed.ts';
-export { getEffectScope } from './scope.ts';
+export { Raw } from './raw.ts';
+export { RunInScope } from './effect-scope.ts';

package/dist/index.js

@@ -1,167 +1,206 @@
-import { Container as y, Token as d } from "@kaokei/di";
+import { Token as y, Container as _, isObject as R, hasOwn as k } from "@kaokei/di";
 export * from "@kaokei/di";
-import { effectScope as P, markRaw as R, reactive as C, getCurrentInstance as h, provide as T, onUnmounted as V, inject as m, hasInjectionContext as b, computed as v } from "vue";
-function E(t, e, n) {
-  return t && t.forEach((o) => {
-    o && o.isCurrentBound(e) && n.push(o.get(e)), o.children && E(o.children, e, n);
-  }), n;
-}
-function D(t, e) {
-  const n = [];
-  return E(e.children, t, n), n[0];
+import { effectScope as w, reactive as A, inject as N, provide as T, onUnmounted as V, getCurrentInstance as H, hasInjectionContext as j, toRaw as F, computed as E, markRaw as K } from "vue";
+const L = new y(
+  "FIND_CHILD_SERVICE"
+), U = new y(
+  "FIND_CHILDREN_SERVICES"
+), p = Symbol("SCOPE_KEY"), c = Symbol("CONTAINER_TOKEN");
+function W(n) {
+  const e = n, t = w(!0);
+  return e[p] = t, t;
+}
+function P(n) {
+  return n[p];
+}
+function Y(n) {
+  const e = n;
+  if (e) {
+    const t = P(e);
+    t && (t.stop(), delete e[p]);
+  }
 }
-function U(t, e) {
-  const n = [];
-  return E(e.children, t, n), n;
+function b(n) {
+  const e = P(n);
+  return e || W(n);
 }
-function A(t) {
-  const e = t, n = P(!0);
-  return e[S] = n, n;
+function h(n, e, t, r) {
+  if (n) {
+    for (const o of n)
+      if (o.isCurrentBound(e) && (t.push(o.get(e)), r) || o.children && h(o.children, e, t, r))
+        return !0;
+  }
+  return !1;
 }
-function I(t) {
-  return t[S];
+function z(n, e) {
+  const t = [];
+  return h(e.children, n, t, !0), t[0];
 }
-function w(t) {
-  const e = I(t);
-  return e || A(t);
+function B(n, e) {
+  const t = [];
+  return h(e.children, n, t, !1), t;
 }
-function F(t) {
-  const e = t;
-  if (e) {
-    const n = I(e);
-    n && (n.stop(), delete e[S]);
-  }
+function G(n, e) {
+  return R(e) ? A(e) : e;
 }
-function H(t) {
-  return t !== null && typeof t == "object";
+function q(n) {
+  return Y(n);
 }
-function x(t, e) {
-  return H(e) ? C(e) : e;
+function J({ container: n }) {
+  return (e) => z(e, n);
 }
-function L(t) {
-  return F(t);
+function M({
+  container: n
+}) {
+  return (e) => B(e, n);
 }
-function j({ container: t }) {
-  return (e) => D(e, t);
+function C(n) {
+  let e;
+  return n ? e = n.createChild() : e = new _(), e.bind(L).toDynamicValue(J), e.bind(U).toDynamicValue(M), e.onActivation(G), e.onDeactivation(q), e;
 }
-function K({
-  container: t
-}) {
-  return (e) => U(e, t);
-}
-function p(t, e) {
-  let n;
-  return t ? n = t.createChild() : n = new y(), e && n.bind(M).toConstantValue(R(e)), n.bind(W).toDynamicValue(j), n.bind(k).toDynamicValue(K), n.onActivation(x), n.onDeactivation(L), n;
-}
-const M = new d(
-  "USE_VUE_SERVICE_CURRENT_COMPONENT"
-), W = new d(
-  "USE_REACT_SERVICE_FIND_CHILD_SERVICE"
-), k = new d(
-  "USE_REACT_SERVICE_FIND_CHILDREN_SERVICES"
-), S = Symbol(), u = "USE_VUE_SERVICE_CONTAINER_TOKEN", a = p();
-function s(t, e) {
+const a = C();
+function u(n, e) {
   if (typeof e == "function")
-    e(t);
+    e(n);
   else
-    for (let n = 0; n < e.length; n++)
-      t.bind(e[n]).toSelf();
-}
-function N() {
-  const t = h();
-  if (t) {
-    const e = u, n = t.provides, o = t.parent && t.parent.provides;
-    if (
-      // 当前实例的provides存在
-      n && // 当前实例的provides已经和parentProvides不是一个对象，说明已经Object.create(parentProvides)
-      n !== o && // provides自身已经具有CONTAINER_TOKEN属性
-      Object.prototype.hasOwnProperty.call(n, e)
-    )
-      return n[e];
+    for (let t = 0; t < e.length; t++)
+      n.bind(e[t]).toSelf();
+}
+function D() {
+  const n = H();
+  if (n) {
+    const e = c, t = n.provides, r = n.parent && n.parent.provides;
+    if (t && t !== r && k(t, e))
+      return t[e];
   }
 }
-function _() {
-  if (b())
-    return m(u, a);
+function S() {
+  if (j())
+    return N(c, a);
   throw new Error("getProvideContainer 只能在 setup 中使用");
 }
-function q(t) {
-  return (N() || _()).get(t);
-}
-function z(t) {
-  return a.get(t);
-}
-function J(t, e) {
-  return e.runWithContext(() => _().get(t));
+function $(n) {
+  return (D() || S()).get(n);
 }
-function Q(t) {
-  const e = N();
+function x(n) {
+  const e = D();
   if (e)
-    s(e, t);
+    u(e, n);
   else {
-    const n = _(), o = h();
-    let r = p(n, o);
-    s(r, t), T(u, r), V(() => {
+    const t = S();
+    let r = C(t);
+    u(r, n), T(c, r), V(() => {
       r.destroy(), r = null;
     });
   }
 }
-function X(t) {
-  s(a, t);
+function ee(n) {
+  return a.get(n);
 }
-function B(t, e) {
+function ne(n) {
+  u(a, n);
+}
+function te(n, e) {
+  return e.runWithContext(() => S().get(n));
+}
+function Q(n, e) {
   e.runWithContext(() => {
-    const n = m(
-      u,
-      null
-    );
-    if (n)
-      s(n, t);
+    const t = N(c, null);
+    if (t)
+      u(t, n);
     else {
-      let o = p(a);
-      s(o, t), e.provide(u, o), e.onUnmount(() => {
-        o.destroy(), o = null;
+      let r = C(a);
+      u(r, n), e.provide(c, r), e.onUnmount(() => {
+        r.destroy(), r = null;
       });
     }
   });
 }
-function Z(t) {
-  return (e) => B(t, e);
-}
-function $(t, e, n) {
-  const o = n.get, r = n.set;
-  return {
-    configurable: !0,
-    enumerable: !0,
-    get() {
-      const c = C(this), f = Symbol.for(e);
-      let i = c[f];
-      if (!i) {
-        const g = w(c).run(() => r ? v({
-          get: () => o.call(c),
-          set: (O) => r.call(c, O)
-        }) : v(() => o.call(c)));
-        i = R({ value: g }), c[f] = i;
+function re(n) {
+  return (e) => Q(n, e);
+}
+function I(n, e) {
+  const t = e.name;
+  return function() {
+    const r = b(this), o = n, g = F(this);
+    let l, s = Object.getPrototypeOf(g);
+    for (; s; ) {
+      const i = Object.getOwnPropertyDescriptor(s, t);
+      if (i && i.set) {
+        l = i.set;
+        break;
       }
-      return i.value.value;
-    },
-    set(c) {
-      const f = C(this), i = Symbol.for(e), l = f[i];
-      l && r && (l.value.value = c);
+      s = Object.getPrototypeOf(s);
     }
+    const d = this, m = l ? r.run(
+      () => E({
+        get: () => o.call(d),
+        set: (i) => l.call(d, i)
+      })
+    ) : r.run(() => E(() => o.call(d)));
+    return Object.defineProperty(g, t, {
+      value: m,
+      writable: !0,
+      configurable: !0,
+      enumerable: !0
+    }), m.value;
   };
 }
+function oe(n, e) {
+  return typeof n == "function" && (e == null ? void 0 : e.kind) === "getter" ? I(n, e) : I;
+}
+function f(n) {
+  return R(n) ? K(n) : n;
+}
+function O(n, e) {
+  if (e.kind === "accessor")
+    return {
+      get() {
+        return n.get.call(this);
+      },
+      set(r) {
+        n.set.call(this, f(r));
+      },
+      init: f
+    };
+  const t = e.name;
+  return e.addInitializer(function() {
+    let r;
+    Object.defineProperty(this, t, {
+      configurable: !0,
+      enumerable: !0,
+      get() {
+        return r;
+      },
+      set(o) {
+        r = f(o);
+      }
+    });
+  }), f;
+}
+function ie(n, e) {
+  return (e == null ? void 0 : e.kind) === "field" || (e == null ? void 0 : e.kind) === "accessor" ? O(n, e) : O;
+}
+function v(n, e) {
+  return function(...t) {
+    const o = b(this).run(() => w());
+    return o.run(() => n.call(this, ...t)), o;
+  };
+}
+function ce(n, e) {
+  return typeof n == "function" && (e == null ? void 0 : e.kind) === "method" ? v(n) : v;
+}
 export {
-  M as CURRENT_COMPONENT,
-  $ as Computed,
-  k as FIND_CHILDREN_SERVICES,
-  W as FIND_CHILD_SERVICE,
-  B as declareAppProviders,
-  Z as declareAppProvidersPlugin,
-  Q as declareProviders,
-  X as declareRootProviders,
-  w as getEffectScope,
-  J as useAppService,
-  z as useRootService,
-  q as useService
+  oe as Computed,
+  U as FIND_CHILDREN_SERVICES,
+  L as FIND_CHILD_SERVICE,
+  ie as Raw,
+  ce as RunInScope,
+  Q as declareAppProviders,
+  re as declareAppProvidersPlugin,
+  x as declareProviders,
+  ne as declareRootProviders,
+  te as useAppService,
+  ee as useRootService,
+  $ as useService
 };

package/dist/raw.d.cts

@@ -0,0 +1,6 @@
+/**
+ * 将值标记为 raw（如果是对象则调用 markRaw，否则原样返回）
+ */
+export declare function ensureRaw(val: unknown): unknown;
+export declare function Raw(): (value: any, context: ClassFieldDecoratorContext | ClassAccessorDecoratorContext) => any;
+export declare function Raw(value: any, context: ClassFieldDecoratorContext | ClassAccessorDecoratorContext): any;

package/dist/raw.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 将值标记为 raw（如果是对象则调用 markRaw，否则原样返回）
+ */
+export declare function ensureRaw(val: unknown): unknown;
+export declare function Raw(): (value: any, context: ClassFieldDecoratorContext | ClassAccessorDecoratorContext) => any;
+export declare function Raw(value: any, context: ClassFieldDecoratorContext | ClassAccessorDecoratorContext): any;

package/dist/scope.d.cts

@@ -1,5 +1,33 @@
 import { EffectScope } from 'vue';
+/**
+ * 本模块用于为类的实例对象管理 Vue 的 EffectScope。
+ *
+ * 核心思路：通过一个 Symbol key（SCOPE_KEY）在实例对象上挂载唯一的 EffectScope，
+ * 从而将该实例相关的 computed、watch 等响应式副作用统一收集到这个 scope 中。
+ * 当实例销毁时，只需 stop 这个 scope，即可自动清理所有关联的响应式副作用，
+ * 避免内存泄漏。
+ *
+ * 设计保证：每个实例对象上最多只存在一个 EffectScope（通过 getEffectScope 懒创建）。
+ */
+/**
+ * 为实例对象创建一个新的 EffectScope，并挂载到对象的 SCOPE_KEY 属性上。
+ * 使用 effectScope(true) 创建独立的（detached）scope，
+ * 使其不受外层 scope 的 stop 影响，生命周期完全由自身控制。
+ */
 export declare function createScope(obj: object): EffectScope;
+/**
+ * 获取实例对象上已有的 EffectScope。
+ * 如果对象上尚未挂载 scope，则返回 undefined。
+ */
 export declare function getScope(obj: object): EffectScope | undefined;
-export declare function getEffectScope(obj: object): EffectScope;
+/**
+ * 移除并停止实例对象上的 EffectScope。
+ * 调用 scope.stop() 会自动清理该 scope 内所有的 computed、watch 等响应式副作用，
+ * 随后从对象上删除 SCOPE_KEY 属性，彻底解除关联。
+ */
 export declare function removeScope(obj: object): void;
+/**
+ * 获取实例对象的 EffectScope，如果不存在则自动创建。
+ * 这是外部最常用的入口函数，保证每个实例对象上有且仅有一个 EffectScope。
+ */
+export declare function getEffectScope(obj: object): EffectScope;

package/dist/scope.d.ts

@@ -1,5 +1,33 @@
 import { EffectScope } from 'vue';
+/**
+ * 本模块用于为类的实例对象管理 Vue 的 EffectScope。
+ *
+ * 核心思路：通过一个 Symbol key（SCOPE_KEY）在实例对象上挂载唯一的 EffectScope，
+ * 从而将该实例相关的 computed、watch 等响应式副作用统一收集到这个 scope 中。
+ * 当实例销毁时，只需 stop 这个 scope，即可自动清理所有关联的响应式副作用，
+ * 避免内存泄漏。
+ *
+ * 设计保证：每个实例对象上最多只存在一个 EffectScope（通过 getEffectScope 懒创建）。
+ */
+/**
+ * 为实例对象创建一个新的 EffectScope，并挂载到对象的 SCOPE_KEY 属性上。
+ * 使用 effectScope(true) 创建独立的（detached）scope，
+ * 使其不受外层 scope 的 stop 影响，生命周期完全由自身控制。
+ */
 export declare function createScope(obj: object): EffectScope;
+/**
+ * 获取实例对象上已有的 EffectScope。
+ * 如果对象上尚未挂载 scope，则返回 undefined。
+ */
 export declare function getScope(obj: object): EffectScope | undefined;
-export declare function getEffectScope(obj: object): EffectScope;
+/**
+ * 移除并停止实例对象上的 EffectScope。
+ * 调用 scope.stop() 会自动清理该 scope 内所有的 computed、watch 等响应式副作用，
+ * 随后从对象上删除 SCOPE_KEY 属性，彻底解除关联。
+ */
 export declare function removeScope(obj: object): void;
+/**
+ * 获取实例对象的 EffectScope，如果不存在则自动创建。
+ * 这是外部最常用的入口函数，保证每个实例对象上有且仅有一个 EffectScope。
+ */
+export declare function getEffectScope(obj: object): EffectScope;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaokei/use-vue-service",
-  "version": "3.0.1",
+  "version": "4.0.0",
   "type": "module",
   "description": "Lightweight Vue 3 state management with dependency injection, inspired by Angular services.",
   "main": "./dist/index.cjs",
@@ -41,31 +41,43 @@
   "scripts": {
     "test": "vitest",
     "coverage": "vitest run --coverage",
-    "dev": "vite",
-    "build": "vue-tsc -b && vite build",
-    "preview": "vite preview",
+    "build": "vue-tsc -b tsconfig.app.json && vite build",
     "clean": "rm -rf dist/*",
     "public": "npm publish --access public",
     "postpublish": "git push origin --follow-tags",
     "prepublishOnly": "npm run clean && npm run build",
     "release": "standard-version -r",
-    "release:first": "standard-version --first-release"
+    "release:first": "standard-version --first-release",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "peerDependencies": {
+    "@kaokei/di": "^5.0.4"
   },
   "devDependencies": {
-    "@kaokei/di": "^3.0.9",
+    "@kaokei/di": "^5.0.4",
     "@types/node": "^22.15.17",
-    "@vitejs/plugin-vue": "^5.2.4",
-    "@vitest/coverage-v8": "^2.1.9",
+    "@vitejs/plugin-vue": "^6.0.0",
+    "@vitest/coverage-v8": "^3.1.1",
     "@vue/test-utils": "^2.4.6",
     "jsdom": "^25.0.1",
     "standard-version": "^9.5.0",
     "typescript": "~5.6.3",
-    "vite": "^5.4.19",
+    "vite": "^6.0.0",
     "vite-plugin-dts": "^4.5.3",
-    "vitest": "^2.1.9",
+    "vitepress": "^1.6.3",
+    "vitest": "^3.1.1",
     "vue": "^3.5.13",
     "vue-router": "^4.5.1",
-    "vue-tsc": "^2.2.10"
+    "vue-tsc": "^2.2.10",
+    "@swc/core": "^1.15.21",
+    "@types/fs-extra": "^11.0.4",
+    "fast-check": "^4.6.0",
+    "fs-extra": "^11.3.0",
+    "inversify": "^6.2.2",
+    "reflect-metadata": "^0.2.2",
+    "unplugin-swc": "^1.5.9"
   },
   "packageManager": "pnpm@9.9.0+sha512.60c18acd138bff695d339be6ad13f7e936eea6745660d4cc4a776d5247c540d0edee1a563695c183a66eb917ef88f2b4feb1fc25f32a7adcadc7aaf3438e99c1"
 }

package/dist/utils.d.cts

@@ -1,3 +0,0 @@
-import { Container } from '@kaokei/di';
-import { ComponentInternalInstance } from 'vue';
-export declare function createContainer(parent?: Container, instance?: ComponentInternalInstance | null): Container;

package/dist/utils.d.ts

@@ -1,3 +0,0 @@
-import { Container } from '@kaokei/di';
-import { ComponentInternalInstance } from 'vue';
-export declare function createContainer(parent?: Container, instance?: ComponentInternalInstance | null): Container;