Utility Functions Reference

This section provides a detailed reference for key utility functions and shared concepts within the TRMNL Salah Prayer Times Plugin backend. These utilities handle cross-cutting concerns such as authentication, error handling, logging, date/time manipulations, and prayer time calculations, ensuring consistency and reusability across the application.

---

Authentication (src/utils/auth.ts)

verifyAuthHeader

verifyAuthHeader(event: APIGatewayProxyEvent): void // Verifies that incoming API Gateway requests contain a valid Bearer token in the Authorization header, skipping verification in local development environments.

---

Error Handling (src/utils/errorHandler.ts, src/utils/errors.ts)

handleError

handleError(message: string, { error, context = {} }: ErrorContext): never // Consistently logs an error with a given message and optional context, then re-throws the original error.

Custom Error Classes

The src/utils/errors.ts file defines a set of custom error classes that extend CustomError, providing standardized HTTP status codes for various error scenarios.

• CustomError(statusCode: number, message: string): A base class for all custom HTTP errors, allowing specification of an HTTP status code.
• BadRequestError(message = 'Bad Request'): Represents a 400 Bad Request error, indicating invalid client input.
• UnauthorizedError(message = 'Unauthorized'): Represents a 401 Unauthorized error, typically for missing or invalid authentication credentials.
• ForbiddenError(message = 'Forbidden'): Represents a 403 Forbidden error, indicating that the client does not have permission to access the resource.
• NotFoundError(message = 'Not Found'): Represents a 404 Not Found error, indicating that the requested resource could not be found.
• ConflictError(message = 'Conflict'): Represents a 409 Conflict error, indicating a conflict with the current state of the resource.
• InternalServerError(message = 'Internal Server Error'): Represents a 500 Internal Server Error, used for unexpected server-side issues.

---

Hijri Date Formatting (src/utils/hijriDate.ts)

formatHijriDate

formatHijriDate(hijriDate: HijriDate): string // Formats a Hijri date object into a readable string (e.g., "15 Ramadan 1444 AH").

---

Logging (src/utils/logger.ts)

logger instance

export const logger = new Logger(); // An instance of @aws-lambda-powertools/logger, used for structured logging across the application, providing enhanced observability in AWS environments.

---

Middleware Utility (src/utils/middify.ts)

middify

middify(handler: Handler): middy.MiddyfiedHandler // Wraps a raw AWS Lambda handler with a set of common Middy.js middleware to enhance its functionality. Key middleware include:

• injectLambdaContext: Injects Lambda context into the logger for richer logs.
• httpErrorHandler: Catches HTTP errors and returns appropriate HTTP responses.
• cors: Adds CORS headers to responses.
• httpEventNormalizer: Normalizes API Gateway proxy events.
• jsonBodyParser: Parses JSON request bodies into JavaScript objects.
• httpUrlEncodeBodyParser: Parses URL-encoded request bodies into JavaScript objects.
• httpResponseSerializer: Serializes response bodies to JSON or plain text based on content type.

---

Prayer Calculation (src/utils/prayerCalculator.ts)

calculateNextPrayer

calculateNextPrayer({ date: currentDate, prayerTimes, timezone }: CalculateNextPrayerParams): NextPrayerInfo // Determines the next upcoming prayer from a list of prayer times and calculates the time remaining until it.

calculateCurrentPrayer

calculateCurrentPrayer(prayerTimes: PrayerTimes, timezone: string, currentDate: Date = new Date()): PrayerName // Identifies the current prayer based on the provided prayer times and the current date, throwing an error if the current time is before Fajr or if prayer times are missing.

---

Prayer Time Parsing (src/utils/prayerTimeParser.ts)

parsePrayerTimes

parsePrayerTimes({ prayerTimesByCity, timezone, date }: ParsePrayerTimesParams): PrayerTimes // Parses prayer times from a raw API response (refer to [Service Layer Reference]) into a structured object where each prayer time is a Date object, adjusted for the specified timezone.

---

Prayer Time Utilities (src/utils/prayerTimeUtils.ts)

formatNextPrayerTime

formatNextPrayerTime(prayerTimesResult: PrayerTimesResult, timezone: string, timeformat: string = '12h'): string // Formats the next prayer's time into a readable string based on the specified timezone and desired time format (12-hour or 24-hour), with fallback handling for formatting errors.

---

Prayer Types (src/utils/prayerTypes.ts)

PrayerName

type PrayerName = 'Fajr' | 'Sunrise' | 'Dhuhr' | 'Asr' | 'Maghrib' | 'Isha'; // A union type defining the common names for daily prayers.

PRAYER_NAMES

export const PRAYER_NAMES: readonly PrayerName[] = [...] // A read-only array containing all defined PrayerName values, useful for iteration and consistent ordering.

PrayerTimes

export interface PrayerTimes { [key: string]: Date; } // An interface representing a collection of prayer times, where each key is a prayer name (string) and its value is a Date object.

---

Time Formatting (src/utils/timeFormatting.ts)

formatTime12h

formatTime12h({ date, timezone }: TimeParams): string // Formats a Date object into a 12-hour time string (e.g., "05:30 AM") for a specified timezone.

formatTime24h

formatTime24h({ date, timezone }: TimeParams): string // Formats a Date object into a 24-hour time string (e.g., "05:30") for a specified timezone.

---

Time Parsing (src/utils/timeParser.ts)

parseTimeString

parseTimeString({ timeString, timezone, date: referenceDate }: ParseTimeStringParams): Date // Converts a time string (e.g., "05:30 AM") into a Date object, anchoring it to a reference date and adjusting for the specified timezone.