@gherk/reactive-architecture 1.0.0

package/dist/knowledge/examples.js

@@ -0,0 +1,829 @@
+// =============================================================================
+// FRAMEWORK-SPECIFIC EXAMPLES
+// =============================================================================
+// Concrete, copy-paste-ready examples implementing the same "Users" feature
+// in different frameworks, all following the Component → Store → Service pattern.
+// =============================================================================
+// ---------------------------------------------------------------------------
+// ANGULAR EXAMPLES (Signals + NgRx SignalStore)
+// ---------------------------------------------------------------------------
+const ANGULAR_MODEL = `
+// models/user.model.ts
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+  isActive: boolean;
+}
+
+export interface CreateUserDto {
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+}
+`;
+const ANGULAR_SERVICE = `
+// services/user.service.ts
+import { Injectable, inject } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { User, CreateUserDto } from '../models/user.model';
+
+@Injectable({ providedIn: 'root' })
+export class UserService {
+  private readonly http = inject(HttpClient);
+  private readonly baseUrl = '/api/users';
+
+  getAll(): Observable<User[]> {
+    return this.http.get<User[]>(this.baseUrl);
+  }
+
+  getById(id: string): Observable<User> {
+    return this.http.get<User>(\`\${this.baseUrl}/\${id}\`);
+  }
+
+  create(data: CreateUserDto): Observable<User> {
+    return this.http.post<User>(this.baseUrl, data);
+  }
+
+  update(id: string, data: Partial<User>): Observable<User> {
+    return this.http.put<User>(\`\${this.baseUrl}/\${id}\`, data);
+  }
+
+  delete(id: string): Observable<void> {
+    return this.http.delete<void>(\`\${this.baseUrl}/\${id}\`);
+  }
+}
+`;
+const ANGULAR_STORE = `
+// store/user.store.ts
+import { computed, inject } from '@angular/core';
+import {
+  signalStore,
+  withState,
+  withComputed,
+  withMethods,
+  patchState,
+} from '@ngrx/signals';
+import { rxMethod } from '@ngrx/signals/rxjs-interop';
+import { pipe, switchMap, tap } from 'rxjs';
+import { tapResponse } from '@ngrx/operators';
+import { UserService } from '../services/user.service';
+import { User } from '../models/user.model';
+
+interface UserState {
+  users: User[];
+  selectedUser: User | null;
+  loading: boolean;
+  error: string | null;
+  loaded: boolean;
+  filter: string;
+}
+
+const initialState: UserState = {
+  users: [],
+  selectedUser: null,
+  loading: false,
+  error: null,
+  loaded: false,
+  filter: '',
+};
+
+export const UserStore = signalStore(
+  { providedIn: 'root' },
+  withState(initialState),
+  withComputed((state) => ({
+    filteredUsers: computed(() => {
+      const filter = state.filter().toLowerCase();
+      if (!filter) return state.users();
+      return state.users().filter(
+        (u) =>
+          u.name.toLowerCase().includes(filter) ||
+          u.email.toLowerCase().includes(filter)
+      );
+    }),
+    activeUsers: computed(() => state.users().filter((u) => u.isActive)),
+    userCount: computed(() => state.users().length),
+  })),
+  withMethods((store, userService = inject(UserService)) => ({
+    loadUsers: rxMethod<void>(
+      pipe(
+        tap(() => patchState(store, { loading: true, error: null })),
+        switchMap(() =>
+          userService.getAll().pipe(
+            tapResponse({
+              next: (users) =>
+                patchState(store, { users, loading: false, loaded: true }),
+              error: (err: Error) =>
+                patchState(store, { error: err.message, loading: false }),
+            })
+          )
+        )
+      )
+    ),
+    setFilter(filter: string) {
+      patchState(store, { filter });
+    },
+    clearError() {
+      patchState(store, { error: null });
+    },
+  }))
+);
+`;
+const ANGULAR_LIST_COMPONENT = `
+// components/user-list/user-list.component.ts
+import { Component, inject, OnInit } from '@angular/core';
+import { UserStore } from '../../store/user.store';
+
+@Component({
+  selector: 'app-user-list',
+  standalone: true,
+  template: \`
+    @if (store.loading()) {
+      <div class="loading">Loading users...</div>
+    }
+
+    @if (store.error(); as error) {
+      <div class="error">{{ error }}</div>
+    }
+
+    <input
+      type="text"
+      placeholder="Filter users..."
+      (input)="store.setFilter($any($event.target).value)"
+    />
+
+    <ul>
+      @for (user of store.filteredUsers(); track user.id) {
+        <li>
+          <span>{{ user.name }}</span>
+          <span>{{ user.email }}</span>
+          <span class="badge">{{ user.role }}</span>
+        </li>
+      }
+    </ul>
+
+    <p>Total: {{ store.userCount() }} users</p>
+  \`,
+})
+export class UserListComponent implements OnInit {
+  readonly store = inject(UserStore);
+
+  ngOnInit() {
+    this.store.loadUsers();
+  }
+}
+`;
+// ---------------------------------------------------------------------------
+// REACT EXAMPLES (Zustand)
+// ---------------------------------------------------------------------------
+const REACT_MODEL = `
+// models/user.model.ts
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+  isActive: boolean;
+}
+
+export interface CreateUserDto {
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+}
+`;
+const REACT_SERVICE = `
+// services/user.service.ts
+import { User, CreateUserDto } from '../models/user.model';
+
+const BASE_URL = '/api/users';
+
+export const userService = {
+  async getAll(): Promise<User[]> {
+    const response = await fetch(BASE_URL);
+    if (!response.ok) throw new Error('Failed to fetch users');
+    return response.json();
+  },
+
+  async getById(id: string): Promise<User> {
+    const response = await fetch(\`\${BASE_URL}/\${id}\`);
+    if (!response.ok) throw new Error('Failed to fetch user');
+    return response.json();
+  },
+
+  async create(data: CreateUserDto): Promise<User> {
+    const response = await fetch(BASE_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+    if (!response.ok) throw new Error('Failed to create user');
+    return response.json();
+  },
+
+  async update(id: string, data: Partial<User>): Promise<User> {
+    const response = await fetch(\`\${BASE_URL}/\${id}\`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+    if (!response.ok) throw new Error('Failed to update user');
+    return response.json();
+  },
+
+  async delete(id: string): Promise<void> {
+    const response = await fetch(\`\${BASE_URL}/\${id}\`, { method: 'DELETE' });
+    if (!response.ok) throw new Error('Failed to delete user');
+  },
+};
+`;
+const REACT_STORE = `
+// store/user.store.ts
+import { create } from 'zustand';
+import { User } from '../models/user.model';
+import { userService } from '../services/user.service';
+
+interface UserState {
+  users: User[];
+  loading: boolean;
+  error: string | null;
+  loaded: boolean;
+  filter: string;
+}
+
+interface UserActions {
+  loadUsers: () => Promise<void>;
+  setFilter: (filter: string) => void;
+  clearError: () => void;
+  getFilteredUsers: () => User[];
+}
+
+export const useUserStore = create<UserState & UserActions>((set, get) => ({
+  // State
+  users: [],
+  loading: false,
+  error: null,
+  loaded: false,
+  filter: '',
+
+  // Actions
+  loadUsers: async () => {
+    set({ loading: true, error: null });
+    try {
+      const users = await userService.getAll();
+      set({ users, loading: false, loaded: true });
+    } catch (err) {
+      set({ error: (err as Error).message, loading: false });
+    }
+  },
+
+  setFilter: (filter: string) => set({ filter }),
+  clearError: () => set({ error: null }),
+
+  // Derived (computed)
+  getFilteredUsers: () => {
+    const { users, filter } = get();
+    if (!filter) return users;
+    const lower = filter.toLowerCase();
+    return users.filter(
+      (u) =>
+        u.name.toLowerCase().includes(lower) ||
+        u.email.toLowerCase().includes(lower)
+    );
+  },
+}));
+`;
+const REACT_LIST_COMPONENT = `
+// components/UserList.tsx
+import { useEffect } from 'react';
+import { useUserStore } from '../store/user.store';
+
+export function UserList() {
+  const { loading, error, loadUsers, setFilter, getFilteredUsers } =
+    useUserStore();
+
+  useEffect(() => {
+    loadUsers();
+  }, [loadUsers]);
+
+  const filteredUsers = getFilteredUsers();
+
+  if (loading) return <div className="loading">Loading users...</div>;
+  if (error) return <div className="error">{error}</div>;
+
+  return (
+    <div>
+      <input
+        type="text"
+        placeholder="Filter users..."
+        onChange={(e) => setFilter(e.target.value)}
+      />
+
+      <ul>
+        {filteredUsers.map((user) => (
+          <li key={user.id}>
+            <span>{user.name}</span>
+            <span>{user.email}</span>
+            <span className="badge">{user.role}</span>
+          </li>
+        ))}
+      </ul>
+
+      <p>Total: {filteredUsers.length} users</p>
+    </div>
+  );
+}
+`;
+// ---------------------------------------------------------------------------
+// VUE EXAMPLES (Pinia)
+// ---------------------------------------------------------------------------
+const VUE_MODEL = `
+// models/user.model.ts
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+  isActive: boolean;
+}
+
+export interface CreateUserDto {
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+}
+`;
+const VUE_SERVICE = `
+// services/user.service.ts
+import type { User, CreateUserDto } from '../models/user.model';
+
+const BASE_URL = '/api/users';
+
+export const userService = {
+  async getAll(): Promise<User[]> {
+    const response = await fetch(BASE_URL);
+    if (!response.ok) throw new Error('Failed to fetch users');
+    return response.json();
+  },
+
+  async getById(id: string): Promise<User> {
+    const response = await fetch(\`\${BASE_URL}/\${id}\`);
+    if (!response.ok) throw new Error('Failed to fetch user');
+    return response.json();
+  },
+
+  async create(data: CreateUserDto): Promise<User> {
+    const response = await fetch(BASE_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+    if (!response.ok) throw new Error('Failed to create user');
+    return response.json();
+  },
+
+  async update(id: string, data: Partial<User>): Promise<User> {
+    const response = await fetch(\`\${BASE_URL}/\${id}\`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+    if (!response.ok) throw new Error('Failed to update user');
+    return response.json();
+  },
+
+  async delete(id: string): Promise<void> {
+    const response = await fetch(\`\${BASE_URL}/\${id}\`, { method: 'DELETE' });
+    if (!response.ok) throw new Error('Failed to delete user');
+  },
+};
+`;
+const VUE_STORE = `
+// store/user.store.ts
+import { defineStore } from 'pinia';
+import { ref, computed } from 'vue';
+import { userService } from '../services/user.service';
+import type { User } from '../models/user.model';
+
+export const useUserStore = defineStore('users', () => {
+  // State
+  const users = ref<User[]>([]);
+  const loading = ref(false);
+  const error = ref<string | null>(null);
+  const loaded = ref(false);
+  const filter = ref('');
+
+  // Getters (computed)
+  const filteredUsers = computed(() => {
+    if (!filter.value) return users.value;
+    const lower = filter.value.toLowerCase();
+    return users.value.filter(
+      (u) =>
+        u.name.toLowerCase().includes(lower) ||
+        u.email.toLowerCase().includes(lower)
+    );
+  });
+
+  const activeUsers = computed(() =>
+    users.value.filter((u) => u.isActive)
+  );
+
+  const userCount = computed(() => users.value.length);
+
+  // Actions
+  async function loadUsers() {
+    loading.value = true;
+    error.value = null;
+    try {
+      users.value = await userService.getAll();
+      loaded.value = true;
+    } catch (err) {
+      error.value = (err as Error).message;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  function setFilter(value: string) {
+    filter.value = value;
+  }
+
+  function clearError() {
+    error.value = null;
+  }
+
+  return {
+    users,
+    loading,
+    error,
+    loaded,
+    filter,
+    filteredUsers,
+    activeUsers,
+    userCount,
+    loadUsers,
+    setFilter,
+    clearError,
+  };
+});
+`;
+const VUE_LIST_COMPONENT = `
+<!-- components/UserList.vue -->
+<script setup lang="ts">
+import { onMounted } from 'vue';
+import { useUserStore } from '../store/user.store';
+
+const store = useUserStore();
+
+onMounted(() => {
+  store.loadUsers();
+});
+</script>
+
+<template>
+  <div>
+    <div v-if="store.loading" class="loading">Loading users...</div>
+    <div v-if="store.error" class="error">{{ store.error }}</div>
+
+    <input
+      type="text"
+      placeholder="Filter users..."
+      @input="store.setFilter(($event.target as HTMLInputElement).value)"
+    />
+
+    <ul>
+      <li v-for="user in store.filteredUsers" :key="user.id">
+        <span>{{ user.name }}</span>
+        <span>{{ user.email }}</span>
+        <span class="badge">{{ user.role }}</span>
+      </li>
+    </ul>
+
+    <p>Total: {{ store.userCount }} users</p>
+  </div>
+</template>
+`;
+// ---------------------------------------------------------------------------
+// SVELTE EXAMPLES (Svelte Stores)
+// ---------------------------------------------------------------------------
+const SVELTE_MODEL = `
+// models/user.model.ts
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+  isActive: boolean;
+}
+
+export interface CreateUserDto {
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+}
+`;
+const SVELTE_SERVICE = `
+// services/user.service.ts
+import type { User, CreateUserDto } from '../models/user.model';
+
+const BASE_URL = '/api/users';
+
+export const userService = {
+  async getAll(): Promise<User[]> {
+    const response = await fetch(BASE_URL);
+    if (!response.ok) throw new Error('Failed to fetch users');
+    return response.json();
+  },
+
+  async getById(id: string): Promise<User> {
+    const response = await fetch(\`\${BASE_URL}/\${id}\`);
+    if (!response.ok) throw new Error('Failed to fetch user');
+    return response.json();
+  },
+
+  async create(data: CreateUserDto): Promise<User> {
+    const response = await fetch(BASE_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+    if (!response.ok) throw new Error('Failed to create user');
+    return response.json();
+  },
+
+  async update(id: string, data: Partial<User>): Promise<User> {
+    const response = await fetch(\`\${BASE_URL}/\${id}\`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+    if (!response.ok) throw new Error('Failed to update user');
+    return response.json();
+  },
+
+  async delete(id: string): Promise<void> {
+    const response = await fetch(\`\${BASE_URL}/\${id}\`, { method: 'DELETE' });
+    if (!response.ok) throw new Error('Failed to delete user');
+  },
+};
+`;
+const SVELTE_STORE = `
+// store/user.store.ts
+import { writable, derived } from 'svelte/store';
+import { userService } from '../services/user.service';
+import type { User } from '../models/user.model';
+
+// State
+const users = writable<User[]>([]);
+const loading = writable(false);
+const error = writable<string | null>(null);
+const loaded = writable(false);
+const filter = writable('');
+
+// Derived (computed)
+const filteredUsers = derived([users, filter], ([$users, $filter]) => {
+  if (!$filter) return $users;
+  const lower = $filter.toLowerCase();
+  return $users.filter(
+    (u) =>
+      u.name.toLowerCase().includes(lower) ||
+      u.email.toLowerCase().includes(lower)
+  );
+});
+
+const activeUsers = derived(users, ($users) =>
+  $users.filter((u) => u.isActive)
+);
+
+const userCount = derived(users, ($users) => $users.length);
+
+// Actions
+async function loadUsers() {
+  loading.set(true);
+  error.set(null);
+  try {
+    const data = await userService.getAll();
+    users.set(data);
+    loaded.set(true);
+  } catch (err) {
+    error.set((err as Error).message);
+  } finally {
+    loading.set(false);
+  }
+}
+
+function setFilter(value: string) {
+  filter.set(value);
+}
+
+function clearError() {
+  error.set(null);
+}
+
+export const userStore = {
+  users,
+  loading,
+  error,
+  loaded,
+  filter,
+  filteredUsers,
+  activeUsers,
+  userCount,
+  loadUsers,
+  setFilter,
+  clearError,
+};
+`;
+const SVELTE_LIST_COMPONENT = `
+<!-- components/UserList.svelte -->
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { userStore } from '../store/user.store';
+
+  const { filteredUsers, loading, error, userCount, loadUsers, setFilter } =
+    userStore;
+
+  onMount(() => {
+    loadUsers();
+  });
+</script>
+
+{#if $loading}
+  <div class="loading">Loading users...</div>
+{/if}
+
+{#if $error}
+  <div class="error">{$error}</div>
+{/if}
+
+<input
+  type="text"
+  placeholder="Filter users..."
+  on:input={(e) => setFilter(e.currentTarget.value)}
+/>
+
+<ul>
+  {#each $filteredUsers as user (user.id)}
+    <li>
+      <span>{user.name}</span>
+      <span>{user.email}</span>
+      <span class="badge">{user.role}</span>
+    </li>
+  {/each}
+</ul>
+
+<p>Total: {$userCount} users</p>
+`;
+// ---------------------------------------------------------------------------
+// EXAMPLE REGISTRY
+// ---------------------------------------------------------------------------
+const EXAMPLES = {
+    angular: {
+        list: {
+            model: ANGULAR_MODEL,
+            service: ANGULAR_SERVICE,
+            store: ANGULAR_STORE,
+            component: ANGULAR_LIST_COMPONENT,
+        },
+        detail: {
+            model: ANGULAR_MODEL,
+            service: ANGULAR_SERVICE,
+            store: ANGULAR_STORE,
+            component: ANGULAR_LIST_COMPONENT, // Reuse for now
+        },
+        form: {
+            model: ANGULAR_MODEL,
+            service: ANGULAR_SERVICE,
+            store: ANGULAR_STORE,
+            component: ANGULAR_LIST_COMPONENT,
+        },
+        crud: {
+            model: ANGULAR_MODEL,
+            service: ANGULAR_SERVICE,
+            store: ANGULAR_STORE,
+            component: ANGULAR_LIST_COMPONENT,
+        },
+    },
+    react: {
+        list: {
+            model: REACT_MODEL,
+            service: REACT_SERVICE,
+            store: REACT_STORE,
+            component: REACT_LIST_COMPONENT,
+        },
+        detail: {
+            model: REACT_MODEL,
+            service: REACT_SERVICE,
+            store: REACT_STORE,
+            component: REACT_LIST_COMPONENT,
+        },
+        form: {
+            model: REACT_MODEL,
+            service: REACT_SERVICE,
+            store: REACT_STORE,
+            component: REACT_LIST_COMPONENT,
+        },
+        crud: {
+            model: REACT_MODEL,
+            service: REACT_SERVICE,
+            store: REACT_STORE,
+            component: REACT_LIST_COMPONENT,
+        },
+    },
+    vue: {
+        list: {
+            model: VUE_MODEL,
+            service: VUE_SERVICE,
+            store: VUE_STORE,
+            component: VUE_LIST_COMPONENT,
+        },
+        detail: {
+            model: VUE_MODEL,
+            service: VUE_SERVICE,
+            store: VUE_STORE,
+            component: VUE_LIST_COMPONENT,
+        },
+        form: {
+            model: VUE_MODEL,
+            service: VUE_SERVICE,
+            store: VUE_STORE,
+            component: VUE_LIST_COMPONENT,
+        },
+        crud: {
+            model: VUE_MODEL,
+            service: VUE_SERVICE,
+            store: VUE_STORE,
+            component: VUE_LIST_COMPONENT,
+        },
+    },
+    svelte: {
+        list: {
+            model: SVELTE_MODEL,
+            service: SVELTE_SERVICE,
+            store: SVELTE_STORE,
+            component: SVELTE_LIST_COMPONENT,
+        },
+        detail: {
+            model: SVELTE_MODEL,
+            service: SVELTE_SERVICE,
+            store: SVELTE_STORE,
+            component: SVELTE_LIST_COMPONENT,
+        },
+        form: {
+            model: SVELTE_MODEL,
+            service: SVELTE_SERVICE,
+            store: SVELTE_STORE,
+            component: SVELTE_LIST_COMPONENT,
+        },
+        crud: {
+            model: SVELTE_MODEL,
+            service: SVELTE_SERVICE,
+            store: SVELTE_STORE,
+            component: SVELTE_LIST_COMPONENT,
+        },
+    },
+};
+export function getExample(framework, pattern) {
+    const example = EXAMPLES[framework]?.[pattern];
+    if (!example)
+        return `No example found for ${framework}/${pattern}`;
+    return `# ${framework.charAt(0).toUpperCase() + framework.slice(1)} — ${pattern.charAt(0).toUpperCase() + pattern.slice(1)} Pattern
+
+Following the **Component → Store → Service** philosophy:
+
+## 1. Model (Define the contract)
+\`\`\`typescript
+${example.model.trim()}
+\`\`\`
+
+## 2. Service (Data access layer — stateless)
+\`\`\`typescript
+${example.service.trim()}
+\`\`\`
+
+## 3. Store (State management — single source of truth)
+\`\`\`typescript
+${example.store.trim()}
+\`\`\`
+
+## 4. Component (UI — reads from store, dispatches to store)
+\`\`\`typescript
+${example.component.trim()}
+\`\`\`
+`;
+}
+export const AVAILABLE_FRAMEWORKS = [
+    'angular',
+    'react',
+    'vue',
+    'svelte',
+];
+export const AVAILABLE_PATTERNS = [
+    'list',
+    'detail',
+    'form',
+    'crud',
+];
+//# sourceMappingURL=examples.js.map