===============
LIBRARY RULES
===============
From library maintainers:
- Use class-based services with dependency injection instead of centralized stores like Pinia/Vuex
- All APIs are imported from @kaokei/use-vue-service; @kaokei/di is a required peer dependency but never imported directly
- Three scope levels available: component-level (useService/declareProviders), global root (useRootService/declareRootProviders), app-level (useAppService/declareAppProviders)
- Mark service classes with @Injectable() decorator to make them injectable via DI container
- Retrieve reactive service instances via useService(), useRootService(), or useAppService() composables
- Use declareProviders() in component setup to bind services to component scope — service lifecycle matches the component's
- Decorators available: @Injectable, @Inject, @autobind, @Computed, @Raw, @RunInScope, @PostConstruct, @PreDestroy, @Self, @SkipSelf, @Optional, @LazyInject
- For Nuxt projects, use @kaokei/nuxt-use-vue-service module for auto-imports instead of manual imports

### Install and Run Project

Source: https://github.com/kaokei/use-vue-service/blob/main/examples/13-nuxt-decorators/README.md

Commands to install dependencies and start the Nuxt development server.

```bash
pnpm install
pnpm run dev
```

--------------------------------

### Install and Run Project Dependencies

Source: https://github.com/kaokei/use-vue-service/blob/main/examples/04-computed-decorator/README.md

Install project dependencies using pnpm and start the application.

```bash
pnpm install
pnpm start
```

--------------------------------

### Install @kaokei/devtools-use-vue-service

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/ecosystem/devtools.md

Install the package using npm or pnpm.

```bash
npm install @kaokei/devtools-use-vue-service
# 或
pnpm add @kaokei/devtools-use-vue-service
```

--------------------------------

### Install @kaokei/nuxt-use-vue-service

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/ecosystem/nuxt-plugin.md

Install the module using npm or pnpm.

```bash
npm install @kaokei/nuxt-use-vue-service
# 或
pnpm add @kaokei/nuxt-use-vue-service
```

--------------------------------

### 组件级服务声明与获取

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/guide/index.md

在组件的 `setup` 函数中调用 `declareProviders` 来声明服务，并使用 `useService` 来获取服务实例。这会在当前组件创建一个子容器。

```ts
import { declareProviders, useService } from '@kaokei/use-vue-service';
import { CountService } from './service.ts';

// 在组件的 setup 中调用
declareProviders([CountService]);
const countService = useService(CountService);
```

--------------------------------

### Start Development Server

Source: https://github.com/kaokei/use-vue-service/blob/main/examples/14-tree-scope-demo/README.md

Start the development server to run the application. This command compiles the code and serves the application locally, typically with hot-reloading enabled.

```bash
pnpm start

```

--------------------------------

### Install Dependencies

Source: https://github.com/kaokei/use-vue-service/blob/main/examples/14-tree-scope-demo/README.md

Install project dependencies using pnpm. This command fetches all the necessary packages listed in the package.json file.

```bash
pnpm install

```

--------------------------------

### Component Usage Example

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/notification-queue.md

Example of how to use the NotificationService within a Vue component to display and manage notifications.

```APIDOC
## Vue Component Usage

### Description
This example demonstrates how to integrate the `NotificationService` into a Vue component using `@kaokei/use-vue-service`. It shows how to declare the service, inject it, and use its methods to trigger and display notifications.

### Setup

1.  **Declare Service**: Use `declareProviders` to make the `NotificationService` available.
2.  **Inject Service**: Use `useService` to get an instance of the `NotificationService`.

### Template

-   **Trigger Buttons**: Buttons to call `notif.success()`, `notif.error()`, `notif.warning()`, and `notif.info()`.
-   **Notification List**: A `TransitionGroup` to display notifications, iterating over `notif.notifications`. Each notification can be dismissed individually using `notif.dismiss(item.id)`.
-   **Clear All Button**: A button to call `notif.clearAll()`, conditionally shown if `notif.hasNotifications` is true. It displays the `notif.visibleCount`.

### Styling

Includes basic CSS for positioning and styling the notification container and individual notifications.
```

--------------------------------

### Using declareAppProvidersPlugin

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/api/index.md

Example of how to import and use the `declareAppProvidersPlugin` to register services with the application.

```typescript
import { createApp } from 'vue';
import { declareAppProvidersPlugin } from '@kaokei/use-vue-service';
import App from './App.vue';

const app = createApp(App);
app.use(declareAppProvidersPlugin([ServiceA, ServiceB]));
app.mount('#app');
```

--------------------------------

### Get App Service Instance

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/api/index.md

Retrieves a service instance from the App container. It first looks in the App container and then falls back to the root container. This API is not suitable for component setup as it requires an explicit `app` instance.

```typescript
function useAppService<T>(token: CommonToken<T>, app: App): T;
```

--------------------------------

### Manually Setup Devtools

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/ecosystem/devtools.md

Manually register the devtools in your main.ts. This is suitable for scenarios where Vite DevTools are not used or precise timing control is needed. For multiple App instances, call setupDevtools for each.

```typescript
// main.ts
import { createApp } from 'vue'
import { setupDevtools } from '@kaokei/devtools-use-vue-service'
import App from './App.vue'

const app = createApp(App)
setupDevtools(app)
app.mount('#app')
```

```typescript
const app1 = createApp(App1)
const app2 = createApp(App2)
setupDevtools(app1)
setupDevtools(app2)
app1.mount('#app1')
app2.mount('#app2')
```

--------------------------------

### Writable Computed Example

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/api/index.md

Example demonstrating a writable computed property using the `@Computed` decorator, including both getter and setter.

```typescript
import { Computed } from '@kaokei/use-vue-service';

class UserService {
  public firstName = '张';
  public lastName = '三';

  @Computed
  public get fullName() {
    return this.firstName + this.lastName;
  }

  public set fullName(val: string) {
    this.firstName = val.slice(0, 1);
    this.lastName = val.slice(1);
  }
}
```

--------------------------------

### Use Product Service in a Vue Component

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/product-list.md

Demonstrates how to use the ProductService within a Vue component using `<script setup>`. It shows how to declare providers, use the service instance, and bind its properties and methods to the template for filtering, displaying, and managing products.

```vue
<script lang="ts" setup>
import { declareProviders, useService } from '@kaokei/use-vue-service';
import { ProductService } from './product.service';

// 声明服务，与当前组件绑定
declareProviders([ProductService]);

// 获取服务实例
const productService = useService(ProductService);

// 添加示例商品
function addDemoProduct() {
  productService.addProduct({
    id: crypto.randomUUID(),
    name: '示例商品',
    category: '电子产品',
    price: 99,
    stock: 10,
  });
}
</script>

<template>
  <div>
    <!-- 筛选工具栏 -->
    <div>
      <input
        v-model="productService.filterKeyword"
        placeholder="搜索商品名称"
      />
      <select v-model="productService.filterCategory">
        <option value="">全部分类</option>
        <option value="电子产品">电子产品</option>
        <option value="食品">食品</option>
      </select>
      <button @click="productService.resetFilters()">重置</button>
    </div>

    <!-- 统计信息 -->
    <p>共 {{ productService.filteredCount }} / {{ productService.totalCount }} 件商品</p>

    <!-- 添加按钮 -->
    <button @click="addDemoProduct()">添加商品</button>

    <!-- 商品列表 -->
    <ul>
      <li v-for="product in productService.filteredProducts" :key="product.id">
        <strong>{{ product.name }}</strong>
        <span>{{ product.category }}</span>
        <span>¥{{ product.price }}</span>
        <span>库存: {{ product.stock }}</span>
        <button @click="productService.removeProduct(product.id)">删除</button>
      </li>
    </ul>

    <!-- 空状态 -->
    <p v-if="productService.filteredProducts.length === 0">
      暂无商品
    </p>
  </div>
</template>
```

--------------------------------

### useAppService

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/api/index.md

Retrieves a service instance from the App container. It searches the App container first and falls back to the root container if not found. This API is not suitable for use within a component's setup function due to the explicit `app` instance requirement.

```APIDOC
## useAppService

```ts
function useAppService<T>(token: CommonToken<T>, app: App): T;
```

### Description

Retrieves a service instance from the App container. It searches the App container first and falls back to the root container if not found. This API is not suitable for use within a component's setup function due to the explicit `app` instance requirement. Use `useService` within components instead.
```

--------------------------------

### HttpService Definition

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/http-service.md

Defines a stateless HTTP service with methods for GET, POST, PUT, and DELETE requests. It supports setting a base URL and common headers, and uses `$fetch` for making requests.

```typescript
import { Injectable, Raw } from '@kaokei/use-vue-service'

interface FetchConfig {
  headers?: Record<string, string>
  params?: Record<string, any>
}

@Raw()
@Injectable()
export class HttpService {
  baseURL = ''

  commonHeaders: Record<string, string> = {}

  setBaseURL(url: string): void {
    this.baseURL = url
  }

  setHeader(key: string, value: string): void {
    this.commonHeaders[key] = value
  }

  removeHeader(key: string): void {
    delete this.commonHeaders[key]
  }

  async get<T = any>(url: string, config?: FetchConfig): Promise<T> {
    return this.request<T>(url, { method: 'GET', ...config })
  }

  async post<T = any>(url: string, body?: any, config?: FetchConfig): Promise<T> {
    return this.request<T>(url, { method: 'POST', body, ...config })
  }

  async put<T = any>(url: string, body?: any, config?: FetchConfig): Promise<T> {
    return this.request<T>(url, { method: 'PUT', body, ...config })
  }

  async delete<T = any>(url: string, config?: FetchConfig): Promise<T> {
    return this.request<T>(url, { method: 'DELETE', ...config })
  }

  // 统一请求入口，合并公共请求头
  private async request<T>(
    url: string,
    config: FetchConfig & { method: string; body?: any }
  ): Promise<T> {
    const fullURL = url.startsWith('http') ? url : `${this.baseURL}${url}`

    const mergedHeaders: Record<string, string> = {
      ...this.commonHeaders,
      ...config.headers,
    }

    return $fetch<T>(fullURL, {
      method: config.method as any,
      headers: mergedHeaders,
      body: config.body,
      params: config.params,
    })
  }
}
```

--------------------------------

### Declare Global Services

Source: https://github.com/kaokei/use-vue-service/blob/main/examples/14-tree-scope-demo/README.md

Declare services at the root level to make them available globally. This setup ensures that services like LoggerService, SwitchService, CounterService, and CountdownService are accessible throughout the application unless overridden by a more specific binding in a child scope.

```ts
declareProviders((container) => {
  container.bind(LoggerService).toSelf();
  container.bind(SwitchService).toSelf();
  container.bind(CounterService).toSelf();
  container.bind(CountdownService).toSelf();
  container.bind(COUNTER_THEME).toConstantValue('#69c0ff');
  container.bind(COUNTDOWN_THEME).toConstantValue('#69c0ff');
});

```

--------------------------------

### Readonly Computed Example

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/api/index.md

Example demonstrating a simple, read-only computed property using the `@Computed` decorator.

```typescript
import { Computed } from '@kaokei/use-vue-service';

class CountService {
  public count = 1;

  @Computed
  public get doubleCount() {
    return this.count * 2;
  }
}
```

--------------------------------

### 全局根级服务声明与获取

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/guide/index.md

使用 `declareRootProviders` 在全局根容器上声明服务，并用 `useRootService` 从根容器获取服务实例。这些服务在整个应用中全局共享。

```ts
import { declareRootProviders, useRootService } from '@kaokei/use-vue-service';
import { GlobalConfigService } from './service.ts';

declareRootProviders([GlobalConfigService]);
const config = useRootService(GlobalConfigService);
```

--------------------------------

### App 级服务声明与获取（插件形式）

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/guide/index.md

使用 `declareAppProvidersPlugin` 返回一个 Vue 插件，用于在 `main.ts` 中声明 App 级服务。组件内通过 `useService` 获取这些服务。

```ts
import { createApp } from 'vue';
import { declareAppProvidersPlugin } from '@kaokei/use-vue-service';
import { AppService } from './service.ts';
import App from './App.vue';

const app = createApp(App);
// 以 Vue 插件形式声明 App 级服务
app.use(declareAppProvidersPlugin([AppService]));
app.mount('#app');
```

--------------------------------

### @Computed Decorator

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/decorator/index.md

The @Computed decorator transforms a class getter into a Vue computed reactive property. It supports both read-only and writable getters. If a setter exists on the prototype chain, it automatically creates a computed({ get, set }) property.

```APIDOC
## @Computed

### Description

Transforms a class getter into a Vue computed reactive property.

### Usage

#### Without Parentheses (Direct Call)
```ts
@Computed
public get doubleCount() {
  return this.count * 2;
}
```

#### With Parentheses (Factory Call)
```ts
@Computed()
public get doubleCount() {
  return this.count * 2;
}
```

### Details

- Supports both read-only and writable getters.
- If a setter exists on the prototype chain, it automatically creates `computed({ get, set })`.
- Refer to [detailed documentation](../api/index.md#computed) for more information.
```

--------------------------------

### 安装 @kaokei/use-vue-service

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/guide/index.md

使用 npm 安装 `@kaokei/di` 和 `@kaokei/use-vue-service`。本库不依赖 `reflect-metadata`，TypeScript 5.0+ 默认支持装饰器。

```sh
npm install @kaokei/di @kaokei/use-vue-service
```

--------------------------------

### App Service Retrieval Pseudocode

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/api/index.md

Illustrates the internal mechanism for retrieving a service using `useAppService`, involving context running and container injection.

```typescript
app.runWithContext(() => {
  // 通过inject获取最近父级组件/祖先组件关联的container对象
  const container = inject(CONTAINER_TOKEN);
  // 通过container.get获取对应的服务
  return container.get(token);
});
```

--------------------------------

### Define Read-Only and Writable Computed Properties with @Computed

Source: https://github.com/kaokei/use-vue-service/blob/main/examples/04-computed-decorator/README.md

Use the @Computed decorator to transform getter properties into Vue's computed properties. This example shows both read-only getters and a getter/setter combination for writable computed properties.

```typescript
export class UserService {
  public firstName = '张';
  public lastName = '三';

  @Computed
  public get fullName(): string {
    return `${this.firstName}${this.lastName}`;
  }

  @Computed
  public get writableFullName(): string {
    return `${this.firstName} ${this.lastName}`;
  }
  public set writableFullName(val: string) {
    this.firstName = val[0];
    this.lastName = val.slice(1).trim();
  }
}
```

--------------------------------

### @Computed Decorator for Vue Getters

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/decorator/index.md

Use @Computed to transform class getters into Vue's reactive computed properties. Supports read-only and writable getters, automatically creating computed({ get, set }) if a setter exists on the prototype.

```typescript
@Computed
public get doubleCount() { return this.count * 2; }
```

```typescript
@Computed()
public get doubleCount() { return this.count * 2; }
```

--------------------------------

### Component Usage of HttpService

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/http-service.md

Demonstrates how to use the HttpService within a Vue component, managing loading, error, and data states independently for multiple concurrent requests.

```vue
<script lang="ts" setup>
import { ref } from 'vue'
import { declareProviders, useService } from '@kaokei/use-vue-service'
import { HttpService } from '~/services/HttpService'

declareProviders([HttpService])
const http = useService(HttpService)

// ===== 每个请求独立管理自己的状态 =====

// 请求 1：获取用户
const userLoading = ref(false)
const userError = ref('')
const user = ref()

async function fetchUser(id: number) {
  userLoading.value = true
  userError.value = ''
  try {
    user.value = await http.get(`/users/${id}`)
  } catch (err: any) {
    userError.value = err.message
  } finally {
    userLoading.value = false
  }
}

// 请求 2：获取列表（与请求 1 的 loading 互不干扰）
const listLoading = ref(false)
const listError = ref('')
const list = ref([])

async function fetchList() {
  listLoading.value = true
  listError.value = ''
  try {
    list.value = await http.get('/posts')
  } catch (err: any) {
    listError.value = err.message
  } finally {
    listLoading.value = false
  }
}

// 请求 3：POST 创建
const createLoading = ref(false)
const createResult = ref('')

async function createPost() {
  createLoading.value = true
  try {
    const result = await http.post('/posts', {
      title: '新文章',
      body: '文章内容',
    })
    createResult.value = `创建成功，ID: ${result.id}`
  } catch (err: any) {
    createResult.value = `失败: ${err.message}`
  } finally {
    createLoading.value = false
  }
}

// 初始化配置
http.setBaseURL('https://jsonplaceholder.typicode.com')
// http.setHeader('Authorization', 'Bearer xxx')
</script>

<template>
  <div>
    <!-- 请求 1 -->
    <div>
      <button @click="fetchUser(1)" :disabled="userLoading">
        {{ userLoading ? '加载中...' : '获取用户' }}
      </button>
      <p v-if="userError" style="color: red">{{ userError }}</p>
      <div v-if="user">
        <strong>{{ user.name }}</strong>
        <span>{{ user.email }}</span>
      </div>
    </div>

    <!-- 请求 2 — loading 与请求 1 互不影响 -->
    <div>
      <button @click="fetchList" :disabled="listLoading">
        {{ listLoading ? '加载中...' : '获取列表' }}
      </button>
      <p v-if="listError" style="color: red">{{ listError }}</p>
      <ul>
        <li v-for="item in list" :key="item.id">{{ item.title }}</li>
      </ul>
    </div>

    <!-- 请求 3 -->
    <div>
      <button @click="createPost" :disabled="createLoading">
        {{ createLoading ? '提交中...' : '创建文章' }}
      </button>
      <p>{{ createResult }}</p>
    </div>
  </div>
</template>

```

--------------------------------

### CountService with Decorators

Source: https://github.com/kaokei/use-vue-service/blob/main/examples/13-nuxt-decorators/README.md

A service demonstrating @Injectable, @Inject, and @Computed decorators for managing state and dependencies.

```typescript
@Injectable()
export class CountService {
  public count = 0;

  @Inject(LoggerService)
  public logger!: LoggerService;

  @Computed
  public get displayCount(): string {
    return `当前计数：${this.count}`;
  }
}
```

--------------------------------

### DataService with @PostConstruct Initialization

Source: https://github.com/kaokei/use-vue-service/blob/main/examples/10-post-construct/README.md

The @PostConstruct decorator marks the `init` method to be automatically called after the service instance is created and dependencies are injected. This method initializes the `data` and `logs` properties.

```typescript
import { Injectable, PostConstruct } from '@nestjs/common';

@Injectable()
export class DataService {
  public data: string[] = [];
  public initialized = false;
  public logs: string[] = ['constructor: 服务实例已创建'];

  @PostConstruct
  public init() {
    this.initialized = true;
    this.data = ['苹果', '香蕉', '橙子'];
    this.logs.push('PostConstruct: init() 已自动执行');
  }
}
```

--------------------------------

### Map Model to API Parameters

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/search-service.md

Override `model2TOParserMap` to transform frontend form field names to backend API parameter names. Useful when a single frontend field maps to multiple backend parameters, like splitting a date range into start and end times.

```typescript
override model2TOParserMap = {
  createTimeRange: (value: [string, string]) => ({
    startTime: value[0],
    endTime: value[1],
  }),
}
```

--------------------------------

### Declare App-Level Service with Plugin

Source: https://github.com/kaokei/use-vue-service/blob/main/examples/03-three-level-scope/README.md

Declare services at the App level using a Vue plugin with `declareAppProvidersPlugin`. This allows for App-specific service configurations that override global ones.

```typescript
app.use(declareAppProvidersPlugin((container) => {
  container.bind(ConfigService).toDynamicValue(() => {
    const s = new ConfigService(); s.scope = 'App 级'; return s;
  });
}));
```

--------------------------------

### Declare Global Root Service

Source: https://github.com/kaokei/use-vue-service/blob/main/examples/03-three-level-scope/README.md

Declare services in the global root container using `declareRootProviders`. This sets up the base level for service availability.

```typescript
declareRootProviders((container) => {
  container.bind(ConfigService).toDynamicValue(() => {
    const s = new ConfigService(); s.scope = '全局根级'; return s;
  });
});
```

--------------------------------

### Using Multiple Countdown Components

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/countdown-service.md

This template demonstrates how to use multiple CountdownText and CountdownBlocks components within a single Vue application. Each component instance manages its own countdown independently, ensuring that different timers do not interfere with each other.

```vue
<template>
  <div>
    <!-- 文本样式：不同结束时间，各自独立 -->
    <CountdownText :total-seconds="90" label="90 秒" />
    <CountdownText :total-seconds="3600" label="1 小时" />

    <!-- 卡片样式：多个实例互不干扰 -->
    <CountdownBlocks :total-seconds="120" label="活动 A（2分钟）" />
    <CountdownBlocks :total-seconds="3661" label="活动 B（1小时1分1秒）" />

    <!-- 混合：文本+卡片共用不同服务实例 -->
    <CountdownText :total-seconds="180" label="抢购" />
    <CountdownBlocks :total-seconds="180" label="同一时长" />
  </div>
</template>
```

--------------------------------

### Use CartService in a Vue Component

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/cart-service.md

Demonstrates how to declare, use, and initialize the CartService within a Vue component. It loads data from localStorage on component mount.

```vue
<script lang="ts" setup>
import { onMounted } from 'vue';
import { declareProviders, useService } from '@kaokei/use-vue-service';
import { CartService } from './cart.service';

// 声明服务，与当前组件绑定
declareProviders([CartService]);

// 获取服务实例
const cart = useService(CartService);

// 组件挂载时从 localStorage 恢复数据
onMounted(() => {
  cart.load();
});
</script>

<template>
  <div>
    <h2>购物车（{{ cart.totalCount }} 件商品）</h2>

    <!-- 空购物车 -->
    <p v-if="cart.items.length === 0">购物车是空的</p>

    <!-- 商品列表 -->
    <ul>
      <li v-for="item in cart.items" :key="item.id">
        <span>{{ item.name }}</span>
        <span>¥{{ item.price }}</span>
        <button @click="cart.updateQuantity(item.id, item.quantity - 1)">-</button>
        <span>{{ item.quantity }}</span>
        <button @click="cart.updateQuantity(item.id, item.quantity + 1)">+</button>
        <button @click="cart.removeItem(item.id)">删除</button>
      </li>
    </ul>

    <!-- 总价 -->
    <p v-if="cart.items.length > 0">
      合计：<strong>¥{{ cart.totalPrice.toFixed(2) }}</strong>
    </p>

    <!-- 清空 -->
    <button v-if="cart.items.length > 0" @click="cart.clear()">
      清空购物车
    </button>
  </div>
</template>
```

--------------------------------

### 定义和使用服务

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/guide/index.md

定义 `LoggerService` 和 `CountService`，其中 `CountService` 依赖 `LoggerService`。在 Vue 组件中，使用 `declareProviders` 声明服务，并用 `useService` 获取服务实例。

```ts
// service.ts —— 定义了 2 个服务，LoggerService 和 CountService
// 其中 CountService 依赖 LoggerService
// @Inject 装饰器来自 @kaokei/di，通过 @kaokei/use-vue-service 重新导出
import { Inject } from '@kaokei/use-vue-service';

export class LoggerService {
  public log(...msg: any[]) {
    console.log('from logger service ==>', ...msg);
  }
}

export class CountService {
  public count = 0;

  @Inject(LoggerService)
  public accessor logger: LoggerService;

  public addOne() {
    this.count++;
    this.logger.log('addOne ==> ', this.count);
  }
}
```

```vue
<script lang="ts" setup>
// 这个组件使用了 service.ts 中定义的服务
import { declareProviders, useService } from '@kaokei/use-vue-service';
import { CountService, LoggerService } from './service.ts';
// 将 CountService、LoggerService 和当前组件进行绑定
declareProviders([CountService, LoggerService]);
// 实例化 CountService 得到一个 countService 对象
// countService 对象自动注入了 logger 属性，是一个 LoggerService 实例
const countService = useService(CountService);
</script>

<template>
  <div>{{ countService.count }}</div>
  <button @click="countService.addOne()">点击按钮+1</button>
</template>
```

--------------------------------

### Equivalent Class Bindings: to vs toSelf

Source: https://github.com/kaokei/use-vue-service/blob/main/examples/08-token-and-binding/README.md

Demonstrates the equivalence of `to(Class)` and `toSelf()` for binding a service identifier to itself. `to(Class)` offers more flexibility for interface-to-implementation bindings.

```typescript
// Both are equivalent:
container.bind(CountService).to(CountService);
container.bind(CountService).toSelf();
```

--------------------------------

### Configure Vite Plugin with appendTo option

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/ecosystem/devtools.md

Use the appendTo option in useVueServiceDevtools to specify an entry module file. The virtual module import will be appended to the head of this file, suitable for SSR or non-HTML injection scenarios.

```typescript
useVueServiceDevtools({ appendTo: 'src/main.ts' })
```

--------------------------------

### Find All Child Services within a Service

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/api/index.md

Demonstrates how to inject and use `FIND_CHILDREN_SERVICES` within a service class to find all instances of another service in the descendant container tree.

```typescript
class DemoService {
  @Inject(FIND_CHILDREN_SERVICES)
  public findAllService!: FindChildrenServices;

  public handleClickBtn() {
    const childServices = this.findAllService(ChildService);
    childServices.forEach(service => service.doSomething());
  }
}
```

--------------------------------

### Vue Component Event Handling

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/search-service.md

Demonstrates correct event handling in Vue components to ensure the `this` context points to the reactive proxy. Use direct method references for simple cases or arrow functions/wrapper methods when passing arguments.

```vue
<!-- Directly pass method reference - safe, this points to reactive proxy -->
<input @input="search.search()" />

<!-- Scenarios requiring arguments - use arrow function or component method wrapper -->
<button @click="search.onPageChange(3)" />
<button @click="goToPage(3)" /> <!-- goToPage internally calls search.onPageChange(3) -->
```

--------------------------------

### Define Product Service with Reactive Array

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/product-list.md

Defines a ProductService using @Injectable and @Computed decorators. It manages a reactive 'products' array and provides methods for CRUD operations and filtering. Use this service to centralize product list management.

```typescript
import { Injectable, Computed } from '@kaokei/use-vue-service';

/** 商品信息 */
interface Product {
  /** 商品 ID */
  id: string;
  /** 商品名称 */
  name: string;
  /** 分类 */
  category: string;
  /** 价格 */
  price: number;
  /** 库存 */
  stock: number;
}

/**
 * 商品列表服务。
 * 
 * 服务实例本身是 Vue reactive 对象，因此 products 数组的
 * 任何变动（push、splice、索引赋值、过滤等）都会自动触发模板更新。
 */
@Injectable()
export class ProductService {
  /** 商品列表（响应式数组） */
  products: Product[] = [];

  /** 当前筛选关键词 */
  filterKeyword = '';

  /** 当前筛选分类 */
  filterCategory = '';

  /**
   * 筛选后的商品列表（响应式派生状态）。
   * 依赖 products、filterKeyword、filterCategory，
   * 任一变化时自动重新计算。
   */
  @Computed()
  get filteredProducts(): Product[] {
    let result = this.products;

    if (this.filterKeyword) {
      const kw = this.filterKeyword.toLowerCase();
      result = result.filter(p => p.name.toLowerCase().includes(kw));
    }

    if (this.filterCategory) {
      result = result.filter(p => p.category === this.filterCategory);
    }

    return result;
  }

  /**
   * 计算商品总数（响应式派生状态）。
   */
  @Computed()
  get totalCount(): number {
    return this.products.length;
  }

  /**
   * 计算筛选后数量。
   */
  @Computed()
  get filteredCount(): number {
    return this.filteredProducts.length;
  }

  /**
   * 添加商品。
   */
  addProduct(product: Product): void {
    this.products.push({ ...product });
  }

  /**
   * 删除商品。
   */
  removeProduct(id: string): void {
    const index = this.products.findIndex(p => p.id === id);
    if (index !== -1) {
      this.products.splice(index, 1);
    }
  }

  /**
   * 更新商品信息。
   */
  updateProduct(id: string, updates: Partial<Product>): void {
    const product = this.products.find(p => p.id === id);
    if (product) {
      Object.assign(product, updates);
    }
  }

  /**
   * 根据 ID 查找商品。
   */
  findById(id: string): Product | undefined {
    return this.products.find(p => p.id === id);
  }

  /**
   * 批量设置商品列表（如从 API 获取数据后整体替换）。
   */
  setProducts(products: Product[]): void {
    this.products = products;
  }

  /**
   * 设置筛选分类。
   */
  setCategory(category: string): void {
    this.filterCategory = category;
  }

  /**
   * 清空筛选条件。
   */
  resetFilters(): void {
    this.filterKeyword = '';
    this.filterCategory = '';
  }
}
```

--------------------------------

### Use Notification Service in Vue Component

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/notification-queue.md

Demonstrates how to declare and use the NotificationService within a Vue component. It shows how to trigger notifications and display them in a UI, including a clear all button that shows the current count of visible notifications.

```vue
<script lang="ts" setup>
import { declareProviders, useService } from '@kaokei/use-vue-service';
import { NotificationService } from './notification.service';

// 声明服务为全局服务（使用 declareRootProviders）
// 或者声明为组件级服务（使用 declareProviders）
declareProviders([NotificationService]);

// 获取服务实例
const notif = useService(NotificationService);
</script>

<template>
  <div>
    <!-- 触发按钮 -->
    <button @click="notif.success('操作成功', '数据已保存')">
      显示成功通知
    </button>
    <button @click="notif.error('操作失败', '请稍后重试')">
      显示错误通知
    </button>
    <button @click="notif.warning('请注意', '数据即将过期')">
      显示警告通知
    </button>

    <!-- 通知列表（固定在右上角） -->
    <div class="notification-container">
      <TransitionGroup name="notif">
        <div
          v-for="item in notif.notifications"
          :key="item.id"
          :class="['notification', `notification--${item.type}`]"
        >
          <strong>{{ item.title }}</strong>
          <p v-if="item.message">{{ item.message }}</p>
          <button @click="notif.dismiss(item.id)">×</button>
        </div>
      </TransitionGroup>
    </div>

    <!-- 清空按钮 -->
    <button
      v-if="notif.hasNotifications"
      @click="notif.clearAll()"
    >
      清空全部 ({{ notif.visibleCount }})
    </button>
  </div>
</template>

<style scoped>
.notification-container {
  position: fixed;
  top: 16px;
  right: 16px;
  z-index: 9999;
  display: flex;
  flex-direction: column;
  gap: 8px;
}

.notification {
  padding: 12px 16px;
  border-radius: 8px;
  min-width: 280px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
  position: relative;
}

.notification--success { background: #f0fdf4; border: 1px solid #22c55e; }
.notification--error   { background: #fef2f2; border: 1px solid #ef4444; }
.notification--warning { background: #fffbeb; border: 1px solid #f59e0b; }
.notification--info    { background: #eff6ff; border: 1px solid #3b82f6; }
</style>
```

--------------------------------

### Define CartService with Reactivity and Persistence

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/cart-service.md

Defines the CartService, including item management, computed totals, and localStorage persistence. The service instance is reactive, and computed properties automatically update.

```typescript
import { Injectable, Computed } from '@kaokei/use-vue-service';

/** 购物车中的商品项 */
interface CartItem {
  /** 商品 ID */
  id: string;
  /** 商品名称 */
  name: string;
  /** 单价 */
  price: number;
  /** 数量 */
  quantity: number;
}

/**
 * 购物车服务。
 * 
 * 服务实例本身是 Vue reactive 对象，因此 items 数组的增删改
 * 会自动触发模板更新，无需手动 ref()/reactive()。
 */
@Injectable()
export class CartService {
  /** 商品列表（响应式数组） */
  items: CartItem[] = [];

  /** localStorage 存储键名 */
  private readonly STORAGE_KEY = 'nuxt_demo_cart';

  /**
   * 计算总价（响应式派生状态）。
   * 当 items 数组变化时自动重新计算。
   */
  @Computed()
  get totalPrice(): number {
    return this.items.reduce(
      (sum, item) => sum + item.price * item.quantity,
      0
    );
  }

  /**
   * 计算商品总数量（响应式派生状态）。
   */
  @Computed()
  get totalCount(): number {
    return this.items.reduce((sum, item) => sum + item.quantity, 0);
  }

  /**
   * 添加商品到购物车。
   * 如果商品已存在则增加数量，否则新增一条记录。
   */
  addItem(item: Omit<CartItem, 'quantity'> & { quantity?: number }): void {
    const existing = this.items.find(i => i.id === item.id);
    if (existing) {
      existing.quantity += item.quantity ?? 1;
    } else {
      this.items.push({
        id: item.id,
        name: item.name,
        price: item.price,
        quantity: item.quantity ?? 1,
      });
    }
    this.save();
  }

  /**
   * 移除指定商品。
   */
  removeItem(id: string): void {
    const index = this.items.findIndex(i => i.id === id);
    if (index !== -1) {
      this.items.splice(index, 1);
      this.save();
    }
  }

  /**
   * 更新商品数量。
   */
  updateQuantity(id: string, quantity: number): void {
    const item = this.items.find(i => i.id === id);
    if (item) {
      item.quantity = Math.max(0, quantity);
      if (item.quantity === 0) {
        this.removeItem(id);
        return;
      }
      this.save();
    }
  }

  /**
   * 清空购物车。
   */
  clear(): void {
    this.items.splice(0, this.items.length);
    this.save();
  }

  /**
   * 从 localStorage 加载购物车数据。
   * 通常在应用初始化时调用。
   */
  load(): void {
    try {
      const raw = localStorage.getItem(this.STORAGE_KEY);
      if (raw) {
        const data = JSON.parse(raw) as CartItem[];
        if (Array.isArray(data)) {
          this.items = data;
        }
      }
    } catch {
      // 数据解析失败，忽略
    }
  }

  /**
   * 保存购物车数据到 localStorage。
   */
  private save(): void {
    try {
      localStorage.setItem(this.STORAGE_KEY, JSON.stringify(this.items));
    } catch {
      // localStorage 写入失败（如配额已满），忽略
    }
  }
}
```

--------------------------------

### SearchService Base Class Inheritance

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/search-service.md

Illustrates the inheritance pattern for SearchService. Subclasses like ArticleSearchService must extend SearchService and override the query method. This pattern enforces type safety and centralized configuration.

```typescript
// Subclass declaration (example, not in source but implied by description)
// class ArticleSearchService extends SearchService<Article> {
//   override defaultModel = {
//     keyword: '',
//     status: '',
//   }
//
//   override query() {
//     // Implementation specific to ArticleSearchService
//     throw new Error('Method not implemented.')
//   }
// }
```

--------------------------------

### Integrate with Vite Plugin

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/ecosystem/devtools.md

Add the useVueServiceDevtools plugin to your vite.config.ts. This method is recommended as it requires no business code changes and automatically injects client code.

```typescript
// vite.config.ts
import vue from '@vitejs/plugin-vue'
import VueDevTools from 'vite-plugin-vue-devtools'
import { useVueServiceDevtools } from '@kaokei/devtools-use-vue-service/vite'

export default defineConfig({
  plugins: [
    vue(),
    VueDevTools(),
    useVueServiceDevtools(), // 放在 VueDevTools() 之后
  ],
})
```

--------------------------------

### TimerService with @RunInScope

Source: https://github.com/kaokei/use-vue-service/blob/main/examples/06-run-in-scope/README.md

This class uses the @RunInScope decorator on the startWatch method. The method contains a watchEffect that logs changes to the 'count' property. The decorator ensures that the watchEffect is managed by an EffectScope, which is returned by the method.

```typescript
export class TimerService {
  public count = 0;
  public logs: string[] = [];

  @RunInScope
  public startWatch(): EffectScope {
    watchEffect(() => {
      this.logs.push(`[watchEffect] count 变为 ${this.count}`);
    });
    return null as any; // 装饰器会替换返回值为 EffectScope
  }
}
```

--------------------------------

### GreetingService with @Computed Decorator

Source: https://github.com/kaokei/use-vue-service/blob/main/examples/13-nuxt-decorators/README.md

A service that uses the @Computed decorator to create a reactive greeting message.

```typescript
export class GreetingService {
  public name = 'Nuxt';

  @Computed
  public get greeting(): string {
    return `你好，${this.name}！欢迎使用 Nuxt 装饰器 🎉`;
  }
}
```

--------------------------------

### CountdownText Component using CountdownService

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/countdown-service.md

A Vue component that displays a countdown timer in a text format. It declares its own instance of CountdownService and initializes it on mount. The `pad` function is a helper for formatting time units.

```vue
<script setup lang="ts">
import { onMounted } from 'vue'
import { CountdownService } from '~/services/CountdownService'

const props = withDefaults(defineProps<{ 
  totalSeconds: number
  label?: string
}>(), {
  label: '',
})

// 每个组件实例拥有独立的 CountdownService
declareProviders([CountdownService])
const cd = useService(CountdownService)

onMounted(() => {
  cd.init(props.totalSeconds)
})

function pad(n: number): string {
  return String(n).padStart(2, '0')
}
</script>

<template>
  <div style="display: inline-flex; align-items: center; gap: 4px; font-family: monospace; font-size: 16px;">
    <span v-if="label" style="color: #999; margin-right: 4px;">{{ label }}</span>
    <template v-if="cd.day > 0">
      <span>{{ cd.day }}</span><span style="color: #999;">天</span>
    </template>
    <span>{{ pad(cd.hour) }}</span><span style="color: #999;">:</span>
    <span>{{ pad(cd.minute) }}</span><span style="color: #999;">:</span>
    <span>{{ pad(cd.second) }}</span>
  </div>
</template>
```

--------------------------------

### Login Form Component Implementation

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/examples/form-validation.md

A Vue.js component demonstrating the usage of FormService for a login form. It defines the model interface, extends FormService to create LoginForm, declares model and rules, and uses the service for data binding, validation, submission, and reset.

```vue
<script lang="ts" setup>
import { Injectable } from '@kaokei/use-vue-service';
import { declareProviders, useService } from '@kaokei/use-vue-service';
import { FormService, required, minLength } from './form.service';

// 1. 定义数据模型
interface LoginModel {
  username: string;
  password: string;
}

// 2. 继承 FormService，声明 model 和 rules
@Injectable()
class LoginForm extends FormService<LoginModel> {
  override model: LoginModel = {
    username: '',
    password: '',
  };

  override rules = {
    username: [required('请输入用户名'), minLength(3, '用户名至少 3 个字符')],
    password: [required('请输入密码'), minLength(6, '密码至少 6 个字符')],
  };
}

// 3. 使用
declareProviders([LoginForm]);
const form = useService(LoginForm);

async function handleLogin() {
  await form.submit(async (model) => {
    console.log('提交数据:', model);
    // 调用登录 API
  });
}
</script>

<template>
  <form @submit.prevent="handleLogin">
    <!-- 用户名 -->
    <div>
      <label>用户名</label>
      <input v-model="form.model.username" @blur="form.touch('username')" />
      <span v-if="form.errors.username" style="color: red">
        {{ form.errors.username }}
      </span>
    </div>

    <!-- 密码 -->
    <div>
      <label>密码</label>
      <input v-model="form.model.password" type="password" @blur="form.touch('password')" />
      <span v-if="form.errors.password" style="color: red">
        {{ form.errors.password }}
      </span>
    </div>

    <!-- 操作 -->
    <button type="submit" :disabled="!form.isValid">登录</button>
    <button
      type="button"
      @click="form.reset({ username: '', password: '' })"
    >
      重置
    </button>
  </form>
</template>
```

--------------------------------

### Find All Child Services with useService

Source: https://github.com/kaokei/use-vue-service/blob/main/docs/api/index.md

Retrieves a function to find all service instances bound to a specific token within the descendant container tree. Returns an array of services.

```typescript
const findAllService = useService(FIND_CHILDREN_SERVICES);
const services = findAllService(Token);
```