@amirulabu/create-recurring-rabbit-app 0.0.0-alpha

package/templates/default/src/lib/monitoring.ts

@@ -0,0 +1,336 @@
+/**
+ * Performance monitoring and query tracking module.
+ *
+ * This module provides tools to track database query performance and identify
+ * slow operations that may impact application responsiveness. It collects timing
+ * data for queries and provides methods to analyze performance patterns.
+ *
+ * Key patterns and conventions:
+ * - Singleton pattern: A single performanceMonitor instance is shared across
+ *   the application to aggregate metrics
+ * - Query keys are truncated to 100 characters to reduce memory usage while
+ *   preserving enough context to identify the query
+ * - Slow queries are logged to console in development mode only
+ * - Metrics are stored in-memory and lost on process restart (by design for simplicity)
+ * - Average duration is used instead of individual samples to identify patterns
+ *
+ * Performance implications:
+ * - Minimal overhead: timing measurements use performance.now() which is
+ *   sub-microsecond precision and has negligible overhead
+ * - Memory usage grows with the number of unique queries but is bounded
+ *   by query key truncation (100 chars per key)
+ * - No disk I/O: All metrics are kept in memory to avoid affecting query performance
+ * - Automatic collection: When wrapping queries with measureQuery/measureSyncQuery,
+ *   timing happens automatically without manual instrumentation
+ *
+ * Configuration decisions:
+ * - SLOW_QUERY_THRESHOLD of 1000ms (1 second) is chosen because:
+ *   - Web requests should ideally complete within 100ms-200ms
+ *   - Database queries over 1 second are noticeably slow and worth investigating
+ *   - Threshold is configurable via getSlowQueries(threshold) parameter
+ * - 100 character query key truncation balances:
+ *   - Memory efficiency (shorter keys = less memory)
+ *   - Debugging utility (enough context to identify the query)
+ * - Development-only logging avoids performance impact in production
+ * - No persistence: In-memory storage is sufficient for development debugging
+ *
+ * Usage patterns:
+ * - Wrap database queries with measureQuery for async operations
+ * - Wrap synchronous operations with measureSyncQuery
+ * - Call getSlowQueries() periodically to analyze performance
+ * - Call reset() to clear metrics (e.g., between test runs)
+ *
+ * @example
+ * // Wrap an async database query
+ * const users = await measureQuery(
+ *   'SELECT * FROM users',
+ *   () => db.query.users.findMany()
+ * )
+ *
+ * @example
+ * // Get slow queries for analysis
+ * const slowQueries = performanceMonitor.getSlowQueries()
+ * slowQueries.forEach(({ query, avgDuration, count }) => {
+ *   console.log(`${query}: ${avgDuration}ms avg (${count} executions)`)
+ * })
+ */
+
+import { env } from './env'
+
+/**
+ * Threshold in milliseconds for considering a query "slow".
+ *
+ * Any query taking longer than this duration will be logged in development
+ * and included in getSlowQueries() results.
+ *
+ * Rationale: 1000ms (1 second) is chosen because:
+ * - User-perceivable delay starts at around 100ms
+ * - Database queries over 1 second indicate potential optimization opportunities
+ * - Allows catching significant performance issues while filtering out
+ *   minor variations that don't impact user experience
+ */
+const SLOW_QUERY_THRESHOLD = 1000 // 1 second in milliseconds
+
+/**
+ * Performance monitoring class for tracking query execution times.
+ *
+ * This class maintains a registry of query execution times and provides
+ * methods to record timings and analyze slow queries. Use the singleton
+ * instance `performanceMonitor` instead of instantiating this class directly.
+ *
+ * Thread safety: This class is not thread-safe but JavaScript is single-threaded,
+ * so this is not a concern in the Node.js runtime.
+ *
+ * Memory usage: Grows linearly with the number of unique queries. Each unique
+ * query stores an array of duration samples. For production use with many
+ * unique queries, consider implementing a periodic cleanup or sampling strategy.
+ */
+export class PerformanceMonitor {
+  /**
+   * Map storing query execution times.
+   *
+   * Key: First 100 characters of the query string
+   * Value: Array of execution durations in milliseconds
+   *
+   * Truncating keys to 100 characters reduces memory usage while preserving
+   * enough context to identify the query. Multiple variations of the same query
+   * (e.g., different WHERE clause values) will be aggregated under the same key,
+   * which is desirable for identifying patterns rather than individual executions.
+   */
+  private queryTimes = new Map<string, number[]>()
+
+  /**
+   * Records the execution time of a query.
+   *
+   * This method should be called immediately after a query completes with the
+   * actual duration measured. If the query exceeds the slow threshold, a warning
+   * will be logged in development mode.
+   *
+   Performance characteristics:
+   * - Time complexity: O(1) for Map insertion
+   * - Space complexity: O(n) where n is the number of unique queries
+   * - Negligible overhead (sub-microsecond for timing recording)
+   *
+   * Security implications:
+   * - Query strings may contain sensitive data (user inputs, etc.)
+   * - In production, avoid logging full queries if they contain PII
+   * - The truncated key (100 chars) reduces exposure risk
+   *
+   * @param query - The SQL query or operation description. Truncated to 100 chars.
+   * @param duration - Execution time in milliseconds. Should be measured using
+   *                   performance.now() for accuracy.
+   *
+   * @example
+   * const startTime = performance.now()
+   * await db.query.users.findMany()
+   * const duration = performance.now() - startTime
+   * performanceMonitor.recordQuery('SELECT * FROM users', duration)
+   */
+  recordQuery(query: string, duration: number) {
+    /**
+     * Truncate query to first 100 characters.
+     *
+     * This serves two purposes:
+     * 1. Memory efficiency: shorter keys use less memory
+     * 2. Pattern aggregation: similar queries with different parameters
+     *    are grouped together for analysis
+     */
+    const queryKey = query.slice(0, 100)
+
+    if (!this.queryTimes.has(queryKey)) {
+      this.queryTimes.set(queryKey, [])
+    }
+
+    this.queryTimes.get(queryKey)!.push(duration)
+
+    /**
+     * Log slow queries in development mode.
+     *
+     * Development-only logging avoids:
+     * - Performance impact in production
+     * - Potential exposure of sensitive query data in production logs
+     * - Log noise in production where performance may be acceptable
+     */
+    if (duration > SLOW_QUERY_THRESHOLD) {
+      if (env.NODE_ENV === 'development') {
+        console.warn(`[Slow Query] ${duration}ms: ${queryKey}`)
+      }
+    }
+  }
+
+  /**
+   * Retrieves all queries that exceed a given average duration threshold.
+   *
+   * This method calculates the average execution time for each query and returns
+   * those whose average exceeds the threshold. Results are sorted by average
+   duration in descending order (slowest first) for prioritization.
+   *
+   * Performance characteristics:
+   * - Time complexity: O(n * m) where n is the number of unique queries and m
+   *   is the average number of samples per query
+   * - Typically very fast unless thousands of queries have been recorded
+   * - Sorting adds O(n log n) overhead
+   *
+   * Use cases:
+   * - Identifying optimization opportunities during development
+   * - Generating performance reports
+   * - Debugging production performance issues (via logging)
+   *
+   * @param threshold - Average duration threshold in milliseconds. Defaults to
+   *                    SLOW_QUERY_THRESHOLD (1000ms). Queries with average
+   *                    duration below this are filtered out.
+   * @returns Array of slow query metrics, sorted by average duration descending.
+   *          Each entry contains the query (truncated), average duration (rounded),
+   *          and execution count.
+   *
+   * @example
+   * const slowQueries = performanceMonitor.getSlowQueries(500)
+   * slowQueries.forEach(({ query, avgDuration, count }) => {
+   *   console.log(`${query}: ${avgDuration}ms average over ${count} executions`)
+   * })
+   */
+  getSlowQueries(
+    threshold = SLOW_QUERY_THRESHOLD
+  ): Array<{ query: string; avgDuration: number; count: number }> {
+    const results: Array<{
+      query: string
+      avgDuration: number
+      count: number
+    }> = []
+
+    this.queryTimes.forEach((durations, query) => {
+      const avgDuration =
+        durations.reduce((a, b) => a + b, 0) / durations.length
+
+      if (avgDuration > threshold) {
+        results.push({
+          query,
+          avgDuration: Math.round(avgDuration),
+          count: durations.length,
+        })
+      }
+    })
+
+    /**
+     * Sort by average duration descending.
+     *
+     * This puts the slowest queries first, which is useful for prioritizing
+     * optimization efforts.
+     */
+    return results.sort((a, b) => b.avgDuration - a.avgDuration)
+  }
+
+  /**
+   * Clears all recorded query metrics.
+   *
+   * This method is useful for:
+   * - Starting fresh measurements after code changes
+   * - Clearing metrics between test runs
+   * - Resetting state in development
+   *
+   * Performance characteristics:
+   * - Time complexity: O(n) where n is the number of unique queries
+   * - Memory is immediately released (in V8, subject to garbage collection)
+   *
+   * @example
+   * // Clear metrics before running a performance test
+   * performanceMonitor.reset()
+   * await runPerformanceTest()
+   * const results = performanceMonitor.getSlowQueries()
+   */
+  reset() {
+    this.queryTimes.clear()
+  }
+}
+
+/**
+ * Singleton instance of PerformanceMonitor.
+ *
+ * Use this instance throughout the application to aggregate metrics from
+ * all parts of the codebase. Having a single instance allows for comprehensive
+ * performance analysis across all database queries and operations.
+ *
+ * @example
+ * import { performanceMonitor } from '@/lib/monitoring'
+ * performanceMonitor.recordQuery('SELECT * FROM users', 125)
+ */
+export const performanceMonitor = new PerformanceMonitor()
+
+/**
+ * Wraps an async function with performance measurement.
+ *
+ * This utility automatically measures the execution time of an async function
+ * and records it with the performance monitor. Use this for database queries,
+ * API calls, or any async operation you want to track.
+ *
+ * Performance characteristics:
+ * - Overhead: ~0.1ms for timing (performance.now() calls)
+ * - Async/await overhead: minimal (<1ms) for Promise wrapping
+ * - Memory: No additional memory allocation per call
+ *
+ * Error handling: Errors are propagated unchanged. The timing measurement
+ * includes the time taken by the function, including any error handling.
+ *
+ * @param query - Description of the operation (e.g., SQL query or function name).
+ *                Used as the key in the performance monitor.
+ * @param fn - The async function to measure. Should return a Promise.
+ * @returns Promise that resolves to the result of fn(), with timing recorded.
+ *
+ * @example
+ * const users = await measureQuery(
+ *   'SELECT * FROM users WHERE active = true',
+ *   () => db.query.users.findMany({ where: { active: true } })
+ * )
+ */
+export function measureQuery<T>(
+  query: string,
+  fn: () => Promise<T>
+): Promise<T> {
+  return new Promise(async (resolve, reject) => {
+    const startTime = performance.now()
+    try {
+      const result = await fn()
+      const duration = performance.now() - startTime
+      performanceMonitor.recordQuery(query, duration)
+      resolve(result)
+    } catch (error) {
+      reject(error)
+    }
+  })
+}
+
+/**
+ * Wraps a synchronous function with performance measurement.
+ *
+ * This utility automatically measures the execution time of a synchronous function
+ * and records it with the performance monitor. Use this for CPU-bound operations,
+ * synchronous I/O, or any synchronous code you want to track.
+ *
+ * Performance characteristics:
+ * - Overhead: ~0.1ms for timing (performance.now() calls)
+ * - Memory: No additional memory allocation per call
+ * - Suitable for operations taking >1ms (otherwise overhead is significant)
+ *
+ * Use cases:
+ * - Tracking synchronous database operations (e.g., SQLite queries)
+ * - Measuring data transformation time
+ * - Profiling CPU-intensive computations
+ *
+ * @param query - Description of the operation (e.g., function name or operation).
+ *                Used as the key in the performance monitor.
+ * @param fn - The synchronous function to measure.
+ * @returns The result of fn(), with timing recorded.
+ *
+ * @example
+ * const users = measureSyncQuery(
+ *   'db.query.users.findMany()',
+ *   () => db.query.users.findMany()
+ * )
+ */
+export function measureSyncQuery<T>(query: string, fn: () => T): T {
+  const startTime = performance.now()
+  const result = fn()
+  const duration = performance.now() - startTime
+  performanceMonitor.recordQuery(query, duration)
+  return result
+}

package/templates/default/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/templates/default/src/server/api/root.ts

@@ -0,0 +1,10 @@
+import { router } from './trpc'
+import { userRouter } from './routers/user'
+import { dashboardRouter } from './routers/dashboard'
+
+export const appRouter = router({
+  user: userRouter,
+  dashboard: dashboardRouter,
+})
+
+export type AppRouter = typeof appRouter

package/templates/default/src/server/api/routers/dashboard.ts

@@ -0,0 +1,37 @@
+import { router, protectedProcedure } from '../trpc'
+import { db } from '@/server/db'
+import { users } from '@/server/db/schema'
+import { eq, and, gte, sql } from 'drizzle-orm'
+
+export const dashboardRouter = router({
+  getStats: protectedProcedure.query(async ({ ctx }) => {
+    const [totalUsersResult] = await db
+      .select({ count: sql<number>`count(*)` })
+      .from(users)
+
+    const [activeUsersResult] = await db
+      .select({ count: sql<number>`count(*)` })
+      .from(users)
+      .where(
+        and(
+          gte(users.createdAt, new Date(Date.now() - 30 * 24 * 60 * 60 * 1000))
+        )
+      )
+
+    return {
+      totalUsers: Number(totalUsersResult?.count ?? 0),
+      activeUsers: Number(activeUsersResult?.count ?? 0),
+      currentUser: ctx.user,
+    }
+  }),
+
+  getUserProfile: protectedProcedure.query(async ({ ctx }) => {
+    const [user] = await db
+      .select()
+      .from(users)
+      .where(eq(users.id, ctx.user.id))
+      .limit(1)
+
+    return user ?? null
+  }),
+})

package/templates/default/src/server/api/routers/user.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod'
+import { router, protectedProcedure } from '../trpc'
+import { db } from '@/server/db'
+import { users } from '@/server/db/schema'
+import { eq } from 'drizzle-orm'
+
+export const userRouter = router({
+  getProfile: protectedProcedure.query(async ({ ctx }) => {
+    const result = await (db
+      .select()
+      .from(users)
+      .where(eq(users.id, ctx.user.id))
+      .limit(1) as any)
+    return result[0] ?? null
+  }),
+
+  updateProfile: protectedProcedure
+    .input(
+      z.object({
+        name: z.string().min(1).max(100),
+      })
+    )
+    .mutation(async ({ ctx, input }) => {
+      const result = await (db
+        .update(users)
+        .set({ name: input.name, updatedAt: new Date() })
+        .where(eq(users.id, ctx.user.id))
+        .returning() as any)
+      return result[0]
+    }),
+})

package/templates/default/src/server/api/trpc.ts

@@ -0,0 +1,132 @@
+/**
+ * tRPC configuration and context setup
+ *
+ * This file sets up the tRPC server with:
+ * - Request context with database connection and authentication
+ * - Middleware for auth checks
+ * - Base procedures (public, protected) for different access levels
+ *
+ * @example
+ * // Create a protected procedure
+ * export const userRouter = router({
+ *   getProfile: protectedProcedure.query(({ ctx }) => {
+ *     return ctx.user
+ *   })
+ * })
+ */
+
+import { initTRPC, TRPCError } from '@trpc/server'
+import { auth } from '@/server/auth/config'
+import { type FetchCreateContextFnOptions } from '@trpc/server/adapters/fetch'
+
+/**
+ * Creates the tRPC context for each request
+ *
+ * This function is called for every tRPC request to create a context object
+ * that is available to all procedures. The context includes:
+ * - User session data from the authentication system
+ * - User information if authenticated, null otherwise
+ *
+ * Architectural decision: Context is created per-request rather than using
+ * a singleton because authentication state varies per request. Using async
+ * context creation allows us to fetch session data from cookies/headers.
+ *
+ * @param opts - Fetch adapter options containing the request object
+ * @param opts.req - The incoming HTTP request with headers
+ * @returns Context object with user and session data
+ *
+ * @example
+ * // The context is automatically used in procedures
+ * const procedure = publicProcedure.query(({ ctx }) => {
+ *   console.log(ctx.user) // User object or null
+ *   console.log(ctx.session) // Session object or null
+ * })
+ */
+export const createTRPCContext = async (opts: FetchCreateContextFnOptions) => {
+  const session = await auth.api.getSession({
+    headers: opts.req.headers,
+  })
+
+  return {
+    user: session?.user ?? null,
+    session: session?.session ?? null,
+  }
+}
+
+/**
+ * Initialized tRPC instance with context typing
+ *
+ * Architectural decision: We use initTRPC with .context() to create a
+ * strongly-typed tRPC instance. This ensures type safety across all routers
+ * and procedures, providing autocomplete and compile-time checks for the
+ * context object structure.
+ */
+const t = initTRPC.context<typeof createTRPCContext>().create()
+
+/**
+ * Router factory function
+ *
+ * Creates a new tRPC router by combining multiple procedures and sub-routers.
+ * Use this to organize API endpoints into logical groups.
+ *
+ * @example
+ * export const appRouter = router({
+ *   greeting: publicProcedure.query(() => 'Hello World'),
+ *   users: userRouter,
+ * })
+ */
+export const router = t.router
+
+/**
+ * Public procedure factory
+ *
+ * Creates a procedure that can be accessed without authentication.
+ * Use this for endpoints that don't require user login.
+ *
+ * Architectural decision: Having explicit public and protected procedures
+ * makes authentication requirements clear and prevents accidental exposure
+ * of protected data. The default is public to reduce friction for new endpoints.
+ *
+ * @example
+ * export const healthRouter = router({
+ *   check: publicProcedure.query(() => ({ status: 'ok' }))
+ * })
+ */
+export const publicProcedure = t.procedure
+
+/**
+ * Protected procedure with authentication middleware
+ *
+ * Creates a procedure that requires user authentication. The middleware
+ * checks if a user is present in the context and throws an UNAUTHORIZED
+ * error if not.
+ *
+ * Architectural decision: This middleware pattern centralizes auth logic
+ * rather than checking authentication in each procedure. It also narrows
+ * the context type to guarantee that ctx.user and ctx.session are non-null,
+ * providing type safety in protected procedures.
+ *
+ * @throws {TRPCError} UNAUTHORIZED if user is not authenticated
+ *
+ * @example
+ * export const userRouter = router({
+ *   getProfile: protectedProcedure.query(({ ctx }) => {
+ *     // ctx.user and ctx.session are guaranteed to be non-null here
+ *     return ctx.user
+ *   })
+ * })
+ */
+export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
+  if (!ctx.user) {
+    throw new TRPCError({
+      code: 'UNAUTHORIZED',
+      message: 'You must be logged in to access this resource',
+    })
+  }
+  return next({
+    ctx: {
+      user: ctx.user,
+      session: ctx.session!,
+    },
+  })
+})