@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/cron-patterns.md

@@ -0,0 +1,327 @@
+---
+name: cron-patterns
+description: Cron job patterns for node-cron scheduling, idempotent tasks, distributed locks, health monitoring, and graceful shutdown.
+---
+
+# Cron Job Patterns
+
+## When to Use
+Use cron patterns for recurring tasks: database cleanup, report generation, cache warming, health checks, subscription billing, and data synchronization. These patterns ensure jobs run reliably, do not overlap, handle failures gracefully, and work correctly in multi-instance deployments. Apply distributed locks when running multiple server instances to prevent duplicate execution.
+
+## How It Works
+
+### node-cron Scheduling
+
+```typescript
+// src/cron/scheduler.ts
+import cron from 'node-cron';
+
+interface CronJob {
+  name: string;
+  schedule: string;
+  handler: () => Promise<void>;
+  enabled: boolean;
+}
+
+const jobs: CronJob[] = [
+  {
+    name: 'cleanup-expired-sessions',
+    schedule: '0 */6 * * *',         // every 6 hours
+    handler: cleanupExpiredSessions,
+    enabled: true,
+  },
+  {
+    name: 'generate-daily-report',
+    schedule: '0 7 * * *',           // daily at 7 AM
+    handler: generateDailyReport,
+    enabled: true,
+  },
+  {
+    name: 'sync-external-data',
+    schedule: '*/15 * * * *',         // every 15 minutes
+    handler: syncExternalData,
+    enabled: true,
+  },
+  {
+    name: 'billing-check',
+    schedule: '0 0 1 * *',           // first of every month
+    handler: processBilling,
+    enabled: true,
+  },
+];
+
+const scheduledTasks: cron.ScheduledTask[] = [];
+
+export function startScheduler() {
+  for (const job of jobs) {
+    if (!job.enabled) continue;
+
+    if (!cron.validate(job.schedule)) {
+      console.error(`Invalid cron schedule for ${job.name}: ${job.schedule}`);
+      continue;
+    }
+
+    const task = cron.schedule(job.schedule, async () => {
+      const start = Date.now();
+      console.log(`[cron] Starting: ${job.name}`);
+
+      try {
+        await job.handler();
+        console.log(`[cron] Completed: ${job.name} (${Date.now() - start}ms)`);
+      } catch (err) {
+        console.error(`[cron] Failed: ${job.name}`, err);
+        await reportCronFailure(job.name, err as Error);
+      }
+    }, {
+      timezone: 'UTC',
+      runOnInit: false,
+    });
+
+    scheduledTasks.push(task);
+    console.log(`[cron] Registered: ${job.name} [${job.schedule}]`);
+  }
+}
+
+export function stopScheduler() {
+  scheduledTasks.forEach((task) => task.stop());
+  console.log(`[cron] Stopped ${scheduledTasks.length} tasks`);
+}
+```
+
+### Idempotent Job Execution
+
+```typescript
+// src/cron/idempotent.ts
+import { db } from '../lib/db';
+
+interface JobRun {
+  jobName: string;
+  runId: string;
+  startedAt: Date;
+  completedAt?: Date;
+  status: 'running' | 'completed' | 'failed';
+  result?: string;
+}
+
+async function runIdempotent(jobName: string, handler: () => Promise<string>): Promise<void> {
+  const runId = `${jobName}-${new Date().toISOString().split('T')[0]}`;
+
+  // Check if already run today
+  const existing = await db.query(
+    'SELECT status FROM cron_runs WHERE run_id = $1',
+    [runId]
+  );
+
+  if (existing.rows.length > 0 && existing.rows[0].status === 'completed') {
+    console.log(`[cron] ${jobName} already completed for this period, skipping`);
+    return;
+  }
+
+  // Record start
+  await db.query(
+    `INSERT INTO cron_runs (job_name, run_id, started_at, status)
+     VALUES ($1, $2, NOW(), 'running')
+     ON CONFLICT (run_id) DO UPDATE SET started_at = NOW(), status = 'running'`,
+    [jobName, runId]
+  );
+
+  try {
+    const result = await handler();
+    await db.query(
+      `UPDATE cron_runs SET completed_at = NOW(), status = 'completed', result = $1
+       WHERE run_id = $2`,
+      [result, runId]
+    );
+  } catch (err) {
+    await db.query(
+      `UPDATE cron_runs SET completed_at = NOW(), status = 'failed', result = $1
+       WHERE run_id = $2`,
+      [(err as Error).message, runId]
+    );
+    throw err;
+  }
+}
+
+// Usage
+async function generateDailyReport() {
+  await runIdempotent('daily-report', async () => {
+    const data = await aggregateMetrics();
+    await saveReport(data);
+    return `Generated report with ${data.totalRecords} records`;
+  });
+}
+```
+
+### Distributed Lock (Redis)
+
+```typescript
+// src/cron/distributed-lock.ts
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL!);
+
+export async function withDistributedLock<T>(
+  lockName: string,
+  ttlMs: number,
+  fn: () => Promise<T>
+): Promise<T | null> {
+  const lockKey = `lock:cron:${lockName}`;
+  const lockValue = `${process.pid}:${Date.now()}`;
+
+  // Acquire lock (NX = only if not exists, PX = TTL in ms)
+  const acquired = await redis.set(lockKey, lockValue, 'PX', ttlMs, 'NX');
+
+  if (!acquired) {
+    console.log(`[cron] Lock "${lockName}" held by another instance, skipping`);
+    return null;
+  }
+
+  try {
+    const result = await fn();
+    return result;
+  } finally {
+    // Release lock only if we still own it (Lua script for atomicity)
+    await redis.eval(
+      `if redis.call("get", KEYS[1]) == ARGV[1] then
+         return redis.call("del", KEYS[1])
+       else
+         return 0
+       end`,
+      1, lockKey, lockValue
+    );
+  }
+}
+
+// Usage: only one instance runs cleanup at a time
+async function cleanupExpiredSessions() {
+  await withDistributedLock('cleanup-sessions', 300_000, async () => {
+    const deleted = await db.query(
+      'DELETE FROM sessions WHERE expires_at < NOW() RETURNING id'
+    );
+    console.log(`Cleaned up ${deleted.rowCount} expired sessions`);
+  });
+}
+```
+
+### Overlap Prevention
+
+```typescript
+// src/cron/no-overlap.ts
+const runningJobs = new Set<string>();
+
+function withNoOverlap(jobName: string, handler: () => Promise<void>) {
+  return async () => {
+    if (runningJobs.has(jobName)) {
+      console.log(`[cron] ${jobName} still running, skipping this invocation`);
+      return;
+    }
+
+    runningJobs.add(jobName);
+    try {
+      await handler();
+    } finally {
+      runningJobs.delete(jobName);
+    }
+  };
+}
+
+// Register with overlap guard
+cron.schedule('*/5 * * * *', withNoOverlap('sync-data', async () => {
+  // This might take 3-10 minutes
+  await syncAllRecords();
+}));
+```
+
+### Health Monitoring
+
+```typescript
+// src/cron/health.ts
+interface CronHealth {
+  name: string;
+  lastRun: string | null;
+  lastStatus: 'completed' | 'failed' | null;
+  nextRun: string;
+  overdue: boolean;
+}
+
+export async function getCronHealth(): Promise<CronHealth[]> {
+  const results: CronHealth[] = [];
+
+  for (const job of jobs) {
+    const lastRun = await db.query(
+      'SELECT started_at, status FROM cron_runs WHERE job_name = $1 ORDER BY started_at DESC LIMIT 1',
+      [job.name]
+    );
+
+    const expression = cron.validate(job.schedule) ? job.schedule : null;
+    const interval = expression ? cron.getTasks().get(job.name) : null;
+
+    results.push({
+      name: job.name,
+      lastRun: lastRun.rows[0]?.started_at?.toISOString() ?? null,
+      lastStatus: lastRun.rows[0]?.status ?? null,
+      nextRun: getNextCronDate(job.schedule).toISOString(),
+      overdue: isOverdue(job.schedule, lastRun.rows[0]?.started_at),
+    });
+  }
+
+  return results;
+}
+
+function isOverdue(schedule: string, lastRun?: Date): boolean {
+  if (!lastRun) return true;
+  const expected = getNextCronDate(schedule, lastRun);
+  return new Date() > new Date(expected.getTime() + 60_000); // 1min grace
+}
+
+// API endpoint
+app.get('/admin/cron/health', async (_req, res) => {
+  const health = await getCronHealth();
+  const allHealthy = health.every((h) => !h.overdue && h.lastStatus !== 'failed');
+  res.status(allHealthy ? 200 : 503).json({ jobs: health });
+});
+```
+
+### Graceful Shutdown
+
+```typescript
+// src/index.ts
+import { startScheduler, stopScheduler } from './cron/scheduler';
+
+startScheduler();
+
+process.on('SIGTERM', async () => {
+  console.log('SIGTERM received, shutting down gracefully...');
+  stopScheduler();
+  // Wait for running jobs to finish (max 30s)
+  const deadline = Date.now() + 30_000;
+  while (runningJobs.size > 0 && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  if (runningJobs.size > 0) {
+    console.warn(`Forcing shutdown with ${runningJobs.size} jobs still running`);
+  }
+  process.exit(0);
+});
+```
+
+## Examples
+
+| Schedule | Cron Expression | Description |
+|----------|----------------|-------------|
+| Every minute | `* * * * *` | Heartbeat, queue polling |
+| Every 15 min | `*/15 * * * *` | Data sync, cache refresh |
+| Hourly | `0 * * * *` | Metrics aggregation |
+| Daily 7 AM | `0 7 * * *` | Reports, digests |
+| Weekly Monday | `0 0 * * 1` | Cleanup, archival |
+| Monthly 1st | `0 0 1 * *` | Billing, invoicing |
+
+## Checklist
+- [ ] All cron expressions validated at startup with `cron.validate()`
+- [ ] Jobs are idempotent (safe to re-run without side effects)
+- [ ] Distributed lock prevents duplicate execution across instances
+- [ ] Overlap guard prevents concurrent runs of the same job
+- [ ] Job runs recorded in database with status, timing, and result
+- [ ] Health endpoint reports last run, status, and overdue state
+- [ ] Graceful shutdown waits for running jobs before exiting
+- [ ] Failed jobs trigger alerts to on-call

package/assets/skills/data-fetching.md

@@ -0,0 +1,231 @@
+---
+name: data-fetching
+description: Data fetching patterns with SWR/TanStack Query, suspense, pagination, infinite scroll, and prefetching.
+---
+
+# Data Fetching
+
+## When to Use
+Apply when building React applications that consume API data. Use TanStack Query (React Query) or SWR for caching, deduplication, and background refetching. These patterns eliminate boilerplate, prevent waterfalls, and keep the UI in sync with server state.
+
+## How It Works
+
+### TanStack Query -- The Standard
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+
+// Fetch with automatic caching, refetching, and error handling
+function UserProfile({ userId }: { userId: string }) {
+  const { data: user, isLoading, error } = useQuery({
+    queryKey: ["user", userId],
+    queryFn: () => fetch(`/api/users/${userId}`).then((r) => r.json()),
+    staleTime: 5 * 60 * 1000, // consider fresh for 5 minutes
+    gcTime: 30 * 60 * 1000,   // keep in cache for 30 minutes
+  });
+
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorMessage error={error} />;
+  return <div>{user.name}</div>;
+}
+
+// Mutation with optimistic update and cache invalidation
+function useUpdateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: { id: string; name: string }) =>
+      fetch(`/api/users/${data.id}`, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(data),
+      }).then((r) => r.json()),
+
+    onMutate: async (newData) => {
+      await queryClient.cancelQueries({ queryKey: ["user", newData.id] });
+      const previous = queryClient.getQueryData(["user", newData.id]);
+      queryClient.setQueryData(["user", newData.id], (old: any) => ({
+        ...old,
+        ...newData,
+      }));
+      return { previous };
+    },
+    onError: (_err, newData, context) => {
+      queryClient.setQueryData(["user", newData.id], context?.previous);
+    },
+    onSettled: (_data, _err, variables) => {
+      queryClient.invalidateQueries({ queryKey: ["user", variables.id] });
+    },
+  });
+}
+```
+
+### SWR -- Lightweight Alternative
+
+```typescript
+import useSWR from "swr";
+
+const fetcher = (url: string) => fetch(url).then((r) => r.json());
+
+function Dashboard() {
+  const { data, error, isLoading, mutate } = useSWR("/api/dashboard", fetcher, {
+    refreshInterval: 30_000,     // poll every 30s
+    revalidateOnFocus: true,     // refetch when tab regains focus
+    dedupingInterval: 2000,      // dedupe requests within 2s
+  });
+
+  // Optimistic update
+  const handleRefresh = () => {
+    mutate(
+      fetch("/api/dashboard").then((r) => r.json()),
+      { optimisticData: { ...data, lastRefresh: new Date() } }
+    );
+  };
+
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorMessage error={error} />;
+  return <DashboardView data={data} onRefresh={handleRefresh} />;
+}
+```
+
+### Cursor-Based Pagination
+
+```typescript
+function useOrders() {
+  return useInfiniteQuery({
+    queryKey: ["orders"],
+    queryFn: ({ pageParam }) =>
+      fetch(`/api/orders?cursor=${pageParam ?? ""}&limit=20`).then((r) => r.json()),
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+  });
+}
+
+function OrderList() {
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useOrders();
+
+  return (
+    <div>
+      {data?.pages.flatMap((page) =>
+        page.orders.map((order: Order) => (
+          <OrderCard key={order.id} order={order} />
+        ))
+      )}
+      {hasNextPage && (
+        <button onClick={() => fetchNextPage()} disabled={isFetchingNextPage}>
+          {isFetchingNextPage ? "Loading..." : "Load More"}
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+### Infinite Scroll with Intersection Observer
+
+```typescript
+function InfiniteOrderList() {
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useOrders();
+  const loadMoreRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries[0].isIntersecting && hasNextPage && !isFetchingNextPage) {
+          fetchNextPage();
+        }
+      },
+      { rootMargin: "200px" }
+    );
+
+    if (loadMoreRef.current) observer.observe(loadMoreRef.current);
+    return () => observer.disconnect();
+  }, [fetchNextPage, hasNextPage, isFetchingNextPage]);
+
+  return (
+    <div>
+      {data?.pages.flatMap((page) =>
+        page.orders.map((order: Order) => (
+          <OrderCard key={order.id} order={order} />
+        ))
+      )}
+      <div ref={loadMoreRef} />
+      {isFetchingNextPage && <Spinner />}
+    </div>
+  );
+}
+```
+
+### Prefetching for Instant Navigation
+
+```typescript
+function OrderRow({ order }: { order: Order }) {
+  const queryClient = useQueryClient();
+
+  // Prefetch on hover so detail page loads instantly
+  const handleMouseEnter = () => {
+    queryClient.prefetchQuery({
+      queryKey: ["order", order.id],
+      queryFn: () => fetch(`/api/orders/${order.id}`).then((r) => r.json()),
+      staleTime: 60_000,
+    });
+  };
+
+  return (
+    <Link
+      href={`/orders/${order.id}`}
+      onMouseEnter={handleMouseEnter}
+    >
+      {order.id} -- ${order.total}
+    </Link>
+  );
+}
+```
+
+### React Suspense Integration
+
+```typescript
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { Suspense } from "react";
+
+function UserProfileSuspense({ userId }: { userId: string }) {
+  const { data: user } = useSuspenseQuery({
+    queryKey: ["user", userId],
+    queryFn: () => fetch(`/api/users/${userId}`).then((r) => r.json()),
+  });
+
+  return <div>{user.name}</div>;
+}
+
+// Parent handles loading and error states
+function UserPage({ userId }: { userId: string }) {
+  return (
+    <ErrorBoundary fallback={<ErrorMessage />}>
+      <Suspense fallback={<Skeleton />}>
+        <UserProfileSuspense userId={userId} />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+```
+
+## Examples
+
+| Pattern | When | Result |
+|---------|------|--------|
+| TanStack Query | Most React apps | Caching, dedup, background refetch |
+| SWR | Simpler needs, smaller bundle | Stale-while-revalidate out of the box |
+| Cursor pagination | Large lists | Consistent results, no offset drift |
+| Infinite scroll | Social feeds, logs | Seamless loading as user scrolls |
+| Prefetch on hover | Detail pages | Instant navigation, zero loading |
+| Suspense | Streaming SSR | Declarative loading states |
+
+## Checklist
+- [ ] All API data fetched through TanStack Query or SWR, not raw useEffect
+- [ ] `staleTime` and `gcTime` configured per query based on data freshness needs
+- [ ] Mutations invalidate related queries for cache consistency
+- [ ] Pagination uses cursor-based approach for large datasets
+- [ ] Infinite scroll uses Intersection Observer with rootMargin
+- [ ] Detail pages prefetched on hover for instant navigation
+- [ ] Error boundaries wrap Suspense-based data fetching
+- [ ] Loading skeletons match the shape of the loaded content