reaparr-pinia-store

Reaparr Pinia Store

IDE Tool Requirement

All frontend file operations and diagnostics MUST use WebStorm MCP tools (webstorm-official-mcp_*, webstorm-index-mcp_*, webstorm-index_ide_*).

Never use Rider MCP tools for any work under src/AppHost/ClientApp/.

---

This skill overrides generic Pinia skills for this project.
Every store uses Composition API, RxJS Observables exclusively for async, and follows a strict internal declaration order.

---

Strict Internal Order

Every store must declare its internals in this exact order — no exceptions:

1. defaultState constant
2. state = reactive<IState>(cloneDeep(defaultState))
3. Inter-store dependencies (use*Store() calls)
4. const actions = { setup(), ..., $reset() }
5. Private helper functions (plain function declarations, not inside actions)
6. const getters = { ... }
7. return { ...toRefs(state), ...actions, ...getters }
8. HMR block (acceptHMRUpdate)

---

Canonical Template

import Log from 'consola';
import { defineStore, acceptHMRUpdate } from 'pinia';
import { reactive, computed, toRefs } from 'vue';
import type { Observable } from 'rxjs';
import { of } from 'rxjs';
import { switchMap, tap, map, catchError } from 'rxjs/operators';
import type { MyDTO } from '@dto';
import { StoreNames, type ISetupResult } from '@interfaces';
import { myApi } from '@api';
import { RefreshDataType } from '@dto';
import { cloneDeep } from 'lodash-es';
import { useSignalrStore } from '@store';

interface IMyStoreState {
  items: MyDTO[];
}

export const useMyStore = defineStore(StoreNames.MyStore, () => {
  // 1. defaultState
  const defaultState: IMyStoreState = { items: [] };

  // 2. state
  const state = reactive<IMyStoreState>(cloneDeep(defaultState));

  // 3. Inter-store deps
  const signalRStore = useSignalrStore();

  // 4. Actions
  const actions = {
    setup(): Observable<ISetupResult> {
      signalRStore
        .getRefreshNotification(RefreshDataType.MyEntity)
        .pipe(switchMap(() => actions.refresh()))
        .subscribe();

      return fetchAndSetItems().pipe(
        map((result) => ({ name: StoreNames.MyStore, isSuccess: !!result?.isSuccess })),
        catchError((err) => {
          Log.error(err);
          return of({ name: StoreNames.MyStore, isSuccess: false });
        }),
      );
    },

    refresh(): Observable<MyDTO[]> {
      return fetchAndSetItems().pipe(map(() => [...state.items]));
    },

    $reset() {
      Object.assign(state, cloneDeep(defaultState));
    },
  };

  // 5. Private helpers
  function fetchAndSetItems() {
    return myApi.getAllEndpoint().pipe(
      tap((result) => {
        if (result.isSuccess) {
          state.items = result.value ?? [];
        }
      }),
    );
  }

  // 6. Getters
  const getters = {
    // Non-reactive lookup — plain function
    getItem: (id: number): MyDTO | null =>
      state.items.find((x) => x.id === id) ?? null,

    // Reactive computed getter
    getVisibleItems: computed((): MyDTO[] => state.items.filter((x) => x.isVisible)),
  };

  // 7. Return
  return { ...toRefs(state), ...actions, ...getters };
});

// 8. HMR
if (import.meta.hot) {
  import.meta.hot.accept(acceptHMRUpdate(useMyStore, import.meta.hot));
}

---

API Endpoints (Generated, Observable-First)

All API endpoints are auto-generated in src/types/api/generated/ and always return Observable<T> — never Promises.

Never instantiate generated classes directly. Import the pre-instantiated singleton from @api:

// ✅ Correct
import { plexServerApi, downloadApi } from '@api';

// ❌ Wrong — never do this
import { PlexServerApi } from '@api/generated/PlexServer';
const api = new PlexServerApi();

Every response shape is { isSuccess: boolean, value?: T }. Always guard on isSuccess:

myApi.getSomething(id).pipe(
  tap((result) => {
    if (result.isSuccess && result.value) {
      // safe to use result.value
    }
  }),
)

---

RxJS Patterns

Reaparr stores are heavily RxJS. Use operators instead of async/await:

Never subscribe inside actions — callers subscribe. The exception is setup(), which subscribes to SignalR notifications internally.

---

State Mutation Rules

---

Getters: Plain vs Computed

const getters = {
  // Plain function — non-reactive, parameterized lookup
  getItem: (id: number): MyDTO | null =>
    state.items.find((x) => x.id === id) ?? null,

  // computed() — reactive, no parameters, used in templates
  getVisibleItems: computed((): MyDTO[] =>
    state.items.filter((x) => x.isVisible)
  ),
};

Use computed() only when the getter is reactive and used directly in templates without arguments.

---

Naming & Registration

• Store export: use<Name>Store (e.g., useServerStore)
• Store ID: entry in StoreNames enum from @interfaces (e.g., StoreNames.ServerStore)
• File name: <name>Store.ts in src/store/
• Barrel export: add export * from './<name>Store'; to src/store/index.ts

Add StoreNames entry first — the enum is in @interfaces, not auto-generated.

---

Path Aliases

---

Logging & Utilities

Logging — always use consola

import Log from 'consola'; // MUST be the first import in the file

Never use console.log, console.error, console.warn, or any other console.*. Use Log.log, Log.error, Log.warn, Log.info, etc.

Utility functions — always prefer lodash-es

Before writing any custom utility (sort, clone, group, deduplicate, merge, pick, omit, …), check lodash-es first. Import only what you need:

import { cloneDeep, orderBy, groupBy, uniqBy, merge, pick, omit } from 'lodash-es';

Never hand-roll implementations that lodash-es already provides.

---