sub2api/frontend/src/stores

Pinia Stores Documentation

This directory contains all Pinia stores for the Sub2API frontend application.

Stores Overview

1. Auth Store (auth.ts)

Manages user authentication state, login/logout, and token persistence.

State:

• user: User | null - Current authenticated user
• token: string | null - JWT authentication token

Computed:

• isAuthenticated: boolean - Whether user is currently authenticated

Actions:

• login(credentials) - Authenticate user with username/password
• register(userData) - Register new user account
• logout() - Clear authentication and logout
• checkAuth() - Restore session from localStorage
• refreshUser() - Fetch latest user data from server

2. App Store (app.ts)

Manages global UI state including sidebar, loading indicators, and toast notifications.

State:

• sidebarCollapsed: boolean - Sidebar collapsed state
• loading: boolean - Global loading state
• toasts: Toast[] - Active toast notifications

Computed:

• hasActiveToasts: boolean - Whether any toasts are active

Actions:

• toggleSidebar() - Toggle sidebar state
• setSidebarCollapsed(collapsed) - Set sidebar state explicitly
• setLoading(isLoading) - Set loading state
• showToast(type, message, duration?) - Show toast notification
• showSuccess(message, duration?) - Show success toast
• showError(message, duration?) - Show error toast
• showInfo(message, duration?) - Show info toast
• showWarning(message, duration?) - Show warning toast
• hideToast(id) - Hide specific toast
• clearAllToasts() - Clear all toasts
• withLoading(operation) - Execute async operation with loading state
• withLoadingAndError(operation, errorMessage?) - Execute with loading and error handling
• reset() - Reset store to defaults

Usage Examples

Auth Store

import { useAuthStore } from '@/stores';

// In component setup
const authStore = useAuthStore();

// Initialize on app startup
authStore.checkAuth();

// Login
try {
  await authStore.login({ username: 'user', password: 'pass' });
  console.log('Logged in:', authStore.user);
} catch (error) {
  console.error('Login failed:', error);
}

// Check authentication
if (authStore.isAuthenticated) {
  console.log('User is logged in:', authStore.user?.username);
}

// Logout
authStore.logout();

App Store

import { useAppStore } from '@/stores';

// In component setup
const appStore = useAppStore();

// Sidebar control
appStore.toggleSidebar();
appStore.setSidebarCollapsed(true);

// Loading state
appStore.setLoading(true);
// ... do work
appStore.setLoading(false);

// Or use helper
await appStore.withLoading(async () => {
  const data = await fetchData();
  return data;
});

// Toast notifications
appStore.showSuccess('Operation completed!');
appStore.showError('Something went wrong!', 5000);
appStore.showInfo('FYI: This is informational');
appStore.showWarning('Be careful!');

// Custom toast
const toastId = appStore.showToast('info', 'Custom message', undefined); // No auto-dismiss
// Later...
appStore.hideToast(toastId);

Combined Usage in Vue Component

<script setup lang="ts">
import { useAuthStore, useAppStore } from '@/stores';
import { onMounted } from 'vue';

const authStore = useAuthStore();
const appStore = useAppStore();

onMounted(() => {
  // Check for existing session
  authStore.checkAuth();
});

async function handleLogin(username: string, password: string) {
  try {
    await appStore.withLoading(async () => {
      await authStore.login({ username, password });
    });
    appStore.showSuccess('Welcome back!');
  } catch (error) {
    appStore.showError('Login failed. Please check your credentials.');
  }
}

async function handleLogout() {
  authStore.logout();
  appStore.showInfo('You have been logged out.');
}
</script>

<template>
  <div>
    <button @click="appStore.toggleSidebar">
      Toggle Sidebar
    </button>
    
    <div v-if="appStore.loading">Loading...</div>
    
    <div v-if="authStore.isAuthenticated">
      Welcome, {{ authStore.user?.username }}!
      <button @click="handleLogout">Logout</button>
    </div>
    <div v-else>
      <button @click="handleLogin('user', 'pass')">Login</button>
    </div>
  </div>
</template>

Persistence

• Auth Store: Token and user data are automatically persisted to localStorage

  • Keys: auth_token, auth_user
  • Restored on checkAuth() call

• App Store: No persistence (UI state resets on page reload)

TypeScript Support

All stores are fully typed with TypeScript. Import types from @/types:

import type { User, Toast, ToastType } from '@/types';

Testing

Stores can be reset to initial state:

// Auth store
authStore.logout(); // Clears all auth state

// App store
appStore.reset(); // Resets to defaults