create-ej-app 25.0.0 → 27.0.0

package/template/nextjs/src/lib/email-service.ts

@@ -1,3 +1,5 @@
+import 'server-only'
+
 import { render, toPlainText } from '@react-email/render'
 import MagicLinkEmail, { MagicLinkEmailProps } from '~/emails/magic-link'
 import WelcomeEmail, { WelcomeEmailProps } from '~/emails/welcome'
@@ -22,6 +24,9 @@ const componentMap: Record<
   magicLink: props => MagicLinkEmail(props as MagicLinkEmailProps)
 }
 
+/**
+ * Generic email template renderer with type-safe overloads
+ */
 async function renderEmailTemplate<T extends EmailTemplateType>(
   templateType: T,
   props: EmailTemplateMap[T]
@@ -40,6 +45,14 @@ async function renderEmailTemplate(
   return { html, text }
 }
 
+/**
+ * Sends welcome email to newly registered users
+ *
+ * @param to - Recipient email address
+ * @param props - Welcome email template props
+ * @returns Promise resolving to SentMessageInfo from nodemailer
+ * @throws Error if sending the email fails
+ */
 export async function sendWelcomeEmail(to: string, props: WelcomeEmailProps) {
   'use workflow'
 
@@ -53,6 +66,14 @@ export async function sendWelcomeEmail(to: string, props: WelcomeEmailProps) {
   })
 }
 
+/**
+ * Sends magic link email for passwordless authentication
+ *
+ * @param to - Recipient email address
+ * @param props - Magic link email template props
+ * @returns Promise resolving to SentMessageInfo from nodemailer
+ * @throws Error if sending the email fails
+ */
 export async function sendMagicLinkEmail(
   to: string,
   props: MagicLinkEmailProps

package/template/nextjs/src/lib/errors.ts

@@ -0,0 +1,74 @@
+/**
+ * Expected, user-safe action failures.
+ *
+ * Throw these for domain and authorization failures. The safe-action
+ * `handleServerError` returns {@link AppError.message} to the client and
+ * records the code on the active span. Unexpected errors stay masked.
+ *
+ * Do not put stack traces, SQL, or internal IDs in `message`.
+ */
+export const AppErrorCode = {
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  NOT_FOUND: 'NOT_FOUND',
+  CONFLICT: 'CONFLICT',
+  QUOTA_EXCEEDED: 'QUOTA_EXCEEDED',
+  FEATURE_NOT_INCLUDED: 'FEATURE_NOT_INCLUDED',
+  BAD_REQUEST: 'BAD_REQUEST',
+  INTERNAL: 'INTERNAL'
+} as const
+
+export type AppErrorCode = (typeof AppErrorCode)[keyof typeof AppErrorCode]
+
+export class AppError extends Error {
+  readonly code: AppErrorCode
+  readonly meta?: Record<string, unknown>
+
+  constructor(
+    code: AppErrorCode,
+    message: string,
+    meta?: Record<string, unknown>
+  ) {
+    super(message)
+    this.name = 'AppError'
+    this.code = code
+    this.meta = meta
+  }
+}
+
+export function isAppError(error: unknown): error is AppError {
+  return error instanceof AppError
+}
+
+/**
+ * The Postgres SQLSTATE of a failed query. Drizzle wraps driver errors and
+ * keeps the original on `cause`, so read both.
+ */
+function postgresCode(error: unknown, depth = 0): unknown {
+  // Drizzle adds one layer; the cap stops an error whose cause points back at
+  // itself from looping forever.
+  if (depth > 5 || typeof error !== 'object' || error === null) return undefined
+  if ('code' in error && typeof error.code === 'string') return error.code
+  return 'cause' in error ? postgresCode(error.cause, depth + 1) : undefined
+}
+
+export function isUniqueViolation(error: unknown): boolean {
+  return postgresCode(error) === '23505'
+}
+
+/**
+ * True when a delete or update is refused because another row still points at
+ * the row: a foreign key violation, or a `restrict` violation for keys declared
+ * `onDelete: 'restrict'`.
+ */
+export function isForeignKeyViolation(error: unknown): boolean {
+  const code = postgresCode(error)
+  return code === '23503' || code === '23001'
+}
+
+export function rethrowUniqueViolation(error: unknown, message: string): never {
+  if (isUniqueViolation(error)) {
+    throw new AppError(AppErrorCode.CONFLICT, message)
+  }
+  throw error
+}

package/template/nextjs/src/lib/format-currency.ts

@@ -1,27 +1,25 @@
-export const formatCurrency = (
-  currencyCode: string,
-  num: number | string,
-  precision = 2
-) => {
-  const numCopy = Number(num)
+const formatters = new Map<string, Intl.NumberFormat>()
 
-  switch (currencyCode) {
-    case 'INR':
-      return new Intl.NumberFormat('en-IN', {
-        style: 'currency',
-        currency: 'INR',
-        signDisplay: 'negative'
-      }).format(numCopy)
-    case 'USD':
-      return new Intl.NumberFormat('en-US', {
-        style: 'currency',
-        currency: 'USD',
-        signDisplay: 'negative'
-      }).format(numCopy)
-    default:
-      console.warn(
-        `Unsupported currency: ${currencyCode}. Defaulting to fixed format.`
-      )
-      return numCopy.toFixed(precision)
+/**
+ * Formats an amount in its currency, such as `$20.00` or `€20.00`.
+ * `Intl` picks the symbol and the minor digits from the ISO currency code.
+ *
+ * @example
+ * formatCurrency('USD', 20) // '$20.00'
+ */
+export function formatCurrency(
+  currencyCode: string,
+  value: number | string
+): string {
+  let formatter = formatters.get(currencyCode)
+  if (!formatter) {
+    formatter = new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: currencyCode,
+      currencyDisplay: 'narrowSymbol',
+      signDisplay: 'negative'
+    })
+    formatters.set(currencyCode, formatter)
   }
+  return formatter.format(Number(value))
 }

package/template/nextjs/src/lib/format-date.ts

@@ -1,12 +1,75 @@
+export type DateFormatOptions = {
+  /** Abbreviated month ("Jan") instead of the full name. */
+  short?: boolean
+  /** Append the time of day. */
+  time?: boolean
+  /** Drop the year. */
+  noYear?: boolean
+  /** Render in this IANA zone instead of the viewer's. */
+  timeZone?: string
+}
+
+function asValidDate(
+  date: Date | string | number | null | undefined
+): Date | null {
+  if (date == null) return null
+  const instant = new Date(date)
+  return Number.isFinite(instant.getTime()) ? instant : null
+}
+
+/**
+ * Date and time are formatted separately and joined with a fixed " at ",
+ * because the connector ICU inserts between them changed across versions
+ * (", " in ICU 72 and later). Bun, Node, and each browser ship different ICU
+ * data, so one `toLocaleString` call renders differently per viewer and
+ * breaks hydration.
+ */
+function joinDateAndTime(
+  instant: Date,
+  dateOptions: Intl.DateTimeFormatOptions,
+  timeOptions: Intl.DateTimeFormatOptions,
+  timeZone: string | undefined
+): string {
+  const zone = timeZone ? { timeZone } : {}
+  const datePart = instant.toLocaleDateString('en-US', {
+    ...dateOptions,
+    ...zone
+  })
+  const timePart = instant.toLocaleTimeString('en-US', {
+    ...timeOptions,
+    ...zone
+  })
+  return `${datePart} at ${timePart}`
+}
+
+/**
+ * Formats a date as an `en-US` string, such as "March 3, 2026".
+ * Returns `-` for a missing or invalid date.
+ */
 export const formatDate = (
   date: Date | string | number | null | undefined,
-  options?: { short?: boolean; time?: boolean; noYear?: boolean }
+  options?: DateFormatOptions
 ): string => {
-  if (date == null) return '—'
-  return new Date(date).toLocaleDateString('en-US', {
+  const instant = asValidDate(date)
+  if (!instant) return '-'
+
+  const dateOptions: Intl.DateTimeFormatOptions = {
     ...(options?.noYear ? {} : { year: 'numeric' }),
     month: options?.short ? 'short' : 'long',
-    day: 'numeric',
-    ...(options?.time ? { hour: '2-digit', minute: '2-digit' } : {})
-  })
+    day: 'numeric'
+  }
+
+  if (!options?.time) {
+    return instant.toLocaleDateString('en-US', {
+      ...dateOptions,
+      ...(options?.timeZone ? { timeZone: options.timeZone } : {})
+    })
+  }
+
+  return joinDateAndTime(
+    instant,
+    dateOptions,
+    { hour: '2-digit', minute: '2-digit' },
+    options.timeZone
+  )
 }

package/template/nextjs/src/lib/nodemailer.ts

@@ -1,16 +1,26 @@
+import 'server-only'
+
 import nodemailer, { SentMessageInfo } from 'nodemailer'
 import { env } from '~/env'
+import { AppError, AppErrorCode } from './errors'
 
+/**
+ * Configure the email transporter using environment variables.
+ * Uses nodemailer for sending emails via SMTP.
+ */
 const transporter = nodemailer.createTransport({
   host: env.EMAIL_SERVER_HOST,
-  port: parseInt(env.EMAIL_SERVER_PORT),
-  secure: parseInt(env.EMAIL_SERVER_PORT) === 465, // Use secure for port 465, false for other ports
+  port: env.EMAIL_SERVER_PORT,
+  secure: env.EMAIL_SERVER_PORT === 465, // Use secure for port 465, false for other ports
   auth: {
     user: env.EMAIL_SERVER_USER,
     pass: env.EMAIL_SERVER_PASSWORD
   }
 })
 
+/**
+ * Interface for the email payload
+ */
 interface SendEmailParams {
   to: string
   subject: string
@@ -18,6 +28,17 @@ interface SendEmailParams {
   html?: string
 }
 
+/**
+ * Sends an email using the configured transporter.
+ *
+ * @param {SendEmailParams} params - The email parameters.
+ * @param {string} params.to - The recipient's email address.
+ * @param {string} params.subject - The subject of the email.
+ * @param {string} [params.text] - The plain text content of the email.
+ * @param {string} [params.html] - The HTML content of the email (optional).
+ * @returns {Promise<any>} Resolves when the email is sent successfully.
+ * @throws {Error} If sending the email fails.
+ */
 export const sendEmail = async ({
   to,
   subject,
@@ -38,6 +59,9 @@ export const sendEmail = async ({
     return info
   } catch (error) {
     console.error('Error sending email:', error)
-    throw new Error('Failed to send email')
+    throw new AppError(
+      AppErrorCode.INTERNAL,
+      'The email was not sent. Try again.'
+    )
   }
 }

package/template/nextjs/src/lib/otel.ts

@@ -1,17 +1,107 @@
-import { SpanStatusCode, trace } from '@opentelemetry/api'
+import { SpanStatusCode, trace, type Attributes } from '@opentelemetry/api'
 
+const MAX_STRING_ATTR_LENGTH = 256
+const MAX_ARRAY_ATTR_ITEMS = 20
+
+/**
+ * Helper function to retrieve the currently active span from the OpenTelemetry context.
+ * Useful for attaching additional information to the current trace.
+ */
 function getSpan() {
   const span = trace.getActiveSpan()
   return span
 }
 
-export function recordWideEvent(attributes: Record<string, any>) {
+/**
+ * Records a "wide event" with arbitrary attributes to the current span.
+ * This allows adding high-cardinality data or domain-specific context
+ * to the trace without starting a new child span.
+ *
+ * @param attributes - Key-value pairs of attributes to add to the span
+ */
+export function recordWideEvent(attributes: Attributes) {
   const span = getSpan()
   if (!span) return
 
   span.setAttributes(attributes)
 }
 
+/**
+ * Flatten a value tree into OTEL-safe attributes under `prefix`.
+ * Nested objects use dotted keys; long strings are truncated; large
+ * arrays are capped. Use for action `parsedInput` on wide events.
+ */
+export function flattenForWideEvent(
+  value: unknown,
+  prefix = 'input'
+): Attributes {
+  const out: Attributes = {}
+
+  const visit = (current: unknown, path: string) => {
+    if (current === null || current === undefined) return
+
+    if (typeof current === 'string') {
+      out[path] =
+        current.length > MAX_STRING_ATTR_LENGTH
+          ? `${current.slice(0, MAX_STRING_ATTR_LENGTH)}…`
+          : current
+      return
+    }
+
+    if (typeof current === 'number' || typeof current === 'boolean') {
+      out[path] = current
+      return
+    }
+
+    if (typeof current === 'bigint') {
+      out[path] = current.toString()
+      return
+    }
+
+    if (Array.isArray(current)) {
+      const limited = current.slice(0, MAX_ARRAY_ATTR_ITEMS)
+      const allPrimitive = limited.every(
+        item =>
+          item === null ||
+          item === undefined ||
+          typeof item === 'string' ||
+          typeof item === 'number' ||
+          typeof item === 'boolean'
+      )
+      if (allPrimitive) {
+        out[path] = limited.map(item =>
+          item === null || item === undefined ? '' : String(item)
+        )
+        if (current.length > MAX_ARRAY_ATTR_ITEMS) {
+          out[`${path}.length`] = current.length
+        }
+        return
+      }
+      out[`${path}.length`] = current.length
+      limited.forEach((item, index) => visit(item, `${path}.${index}`))
+      return
+    }
+
+    if (typeof current === 'object') {
+      for (const [key, child] of Object.entries(
+        current as Record<string, unknown>
+      )) {
+        visit(child, path ? `${path}.${key}` : key)
+      }
+    }
+  }
+
+  visit(value, prefix)
+  return out
+}
+
+/**
+ * Records an exception to the current span and sets the span status to ERROR.
+ * captures the error message and stack trace if available.
+ *
+ * @param err - The error to record (can be an Error object or unknown)
+ * @returns The trace ID associated with the error, useful for correlation
+ */
 export function recordError(err: unknown) {
   const span = getSpan()
   if (!span) return

package/template/nextjs/src/lib/safe-action-client.ts

@@ -8,25 +8,52 @@ import {
 } from '@tanstack/react-query'
 import type { SafeActionResult } from 'next-safe-action'
 
-type AnyAction = (
+/** Type helper for any server action function */
+export type AnyAction = (
   ...args: any[]
 ) => Promise<SafeActionResult<any, any, any, any, any>>
+
+/** Extracts the input type from a server action */
 type ActionInput<T extends AnyAction> = Parameters<T>[0]
+
+/** Extracts the data type from a server action result */
 type ActionData<T extends AnyAction> = Awaited<ReturnType<T>>['data']
 
+/**
+ * Client-side error for server action failures.
+ * Carries the user-facing `serverError` string (including unmasked AppError
+ * messages) and optional Zod validation errors.
+ */
 class SafeActionError extends Error {
   constructor(
     public message: string,
     public validationErrors?: Record<string, string[] | undefined>
   ) {
     super(message)
+    this.name = 'SafeActionError'
   }
 }
 
+/**
+ * React Query hook for server actions that fetch data
+ * Wraps server actions with proper error handling and caching support
+ *
+ * @param key - Unique query key for caching
+ * @param action - Server action function to execute
+ * @param input - Input parameters for the server action (optional)
+ * @param options - React Query options (staleTime, refetchInterval, etc.)
+ *
+ * @returns React Query result with data, loading, and error states
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading } = useSafeActionQuery('cart-items', getCartItems)
+ * ```
+ */
 export function useSafeActionQuery<TAction extends AnyAction>(
   key: string,
   action: TAction,
-  input: ActionInput<TAction>,
+  input?: ActionInput<TAction>,
   options?: Omit<UseQueryOptions<ActionData<TAction>>, 'queryKey' | 'queryFn'>
 ) {
   return useQuery({
@@ -39,7 +66,10 @@ export function useSafeActionQuery<TAction extends AnyAction>(
       }
 
       if (result?.validationErrors) {
-        throw new SafeActionError('Validation failed', result.validationErrors)
+        throw new SafeActionError(
+          'Check the highlighted fields and try again.',
+          result.validationErrors
+        )
       }
 
       return result?.data
@@ -48,13 +78,31 @@ export function useSafeActionQuery<TAction extends AnyAction>(
   })
 }
 
+/**
+ * React Query mutation hook for server actions that modify data
+ * Wraps server actions with proper error handling and optimistic updates support
+ *
+ * @param action - Server action function to execute
+ * @param options - React Query mutation options (onSuccess, onError, etc.)
+ *
+ * @returns React Query mutation result with mutate function and states
+ *
+ * @example
+ * ```tsx
+ * const { mutate, isPending } = useSafeActionMutation(addToCart, {
+ *   onSuccess: (data) => {
+ *     toastSuccessMessage('Added to cart!')
+ *     queryClient.invalidateQueries({ queryKey: ['cart-items'] })
+ *   },
+ *   onError: (error) => {
+ *     toastActionError(error, 'Failed to add to cart')
+ *   }
+ * })
+ * ```
+ */
 export function useSafeActionMutation<TAction extends AnyAction>(
   action: TAction,
-  options?: UseMutationOptions<
-    ActionData<TAction>,
-    SafeActionError,
-    ActionInput<TAction>
-  >
+  options?: UseMutationOptions<ActionData<TAction>, Error, ActionInput<TAction>>
 ) {
   return useMutation({
     mutationFn: async (input: ActionInput<TAction>) => {
@@ -65,7 +113,10 @@ export function useSafeActionMutation<TAction extends AnyAction>(
       }
 
       if (result?.validationErrors) {
-        throw new SafeActionError('Validation failed', result.validationErrors)
+        throw new SafeActionError(
+          'Check the highlighted fields and try again.',
+          result.validationErrors
+        )
       }
 
       return result?.data