Cleanup schema.ics.ts

Add documentation, fix bugs and optimize code

Author: olillin

pages/api/schema.ics.ts

@@ -2,59 +2,119 @@ import { Calendar, ONE_MINUTE_MS, parseCalendar } from 'iamcal'
 import { NextApiRequest, NextApiResponse } from 'next'
 import { prisma } from '../../prisma/prismaclient'
 
-/** Represents the default calendar cache expiration time, in minutes. */
-const DEFAULT_CALENDAR_CACHE_EXPIRATION = 180 // Three hours in minutes
+/** Represents the default expiration time of the calendar cache, in minutes. */
+const DEFAULT_CALENDAR_CACHE_EXPIRATION_TIME = 180 // Three hours in minutes
 
-/** Represents the calendar cache expiration time, in minutes. */
-const calendarCacheExpiration = getCalendarCacheExpiration()
+/** Represents the expiration time of the calendar cache, in minutes. */
+const calendarCacheExpirationTime = getCalendarCacheExpirationTime()
 
-function getCalendarCacheExpiration(
-  defaultMinutes: number = DEFAULT_CALENDAR_CACHE_EXPIRATION
+/**
+ * Get calendar cache expiration time from the environment.
+ * @param defaultExpirationMinutes The time to return if `CALENDAR_CACHE_EXPIRATION_TIME` is unset or invalid.
+ * @returns The parsed value of `CALENDAR_CACHE_EXPIRATION_TIME` or the default time, in minutes.
+ */
+function getCalendarCacheExpirationTime(
+  defaultExpirationMinutes: number = DEFAULT_CALENDAR_CACHE_EXPIRATION_TIME
 ) {
-  try {
-    if (process.env.CALENDAR_CACHE_EXPIRATION) {
-      return parseInt(process.env.CALENDAR_CACHE_EXPIRATION)
-    } else {
-      return defaultMinutes
+  const environmentExpirationTime = process.env.CALENDAR_CACHE_EXPIRATION_TIME
+
+  if (environmentExpirationTime) {
+    try {
+      return parseInt(environmentExpirationTime)
+    } catch {
+      console.warn(
+        `Failed to parse calendar cache expiration time "${environmentExpirationTime}" ` +
+          `from environment, should be an integer representing the time in minutes. ` +
+          `Using default time of ${defaultExpirationMinutes} minutes.`
+      )
     }
-  } catch {
-    console.warn(
-      `Failed to parse calendar cache expiration "${process.env.CALENDAR_CACHE_EXPIRATION}", ` +
-      `should be an integer representing the time in minutes. `+ 
-      `Using default time of ${defaultMinutes} minutes.`
-    )
-    return defaultMinutes
   }
+
+  return defaultExpirationMinutes
 }
 
-let cachedCalendarBody: string | null = null
-let cachedCalendarTime: number = 0
-let cachedCalendarUrls: string = ''
+class CachedCalendar {
+  /** The serialized body of the calendar in iCalendar format. */
+  calendarBody: string
+  /** The URLs this calendar was created from. */
+  urls: string[]
+  /** How long after creation the cache will be considered stale, in minutes.  */
+  expirationTimeMinutes: number
+  /** The time when this cache was created. Expressed in milliseconds elapsed since midnight, January 1, 1970 Universal Coordinated Time (UTC). */
+  time: number
+
+  /**
+   * @param calendarBody The serialized body of the calendar in iCalendar format.
+   * @param urls The URLs this calendar was created from.
+   * @param expirationTime How long after creation the cache will be considered stale, in minutes.
+   */
+  constructor(
+    calendarBody: string,
+    urls: string[],
+    expirationTime: number = calendarCacheExpirationTime
+  ) {
+    this.calendarBody = calendarBody
+    this.urls = urls
+    this.expirationTimeMinutes = expirationTime
+    this.time = Date.now()
+  }
+
+  /**
+   * Get the age of this cache.
+   * @returns The age of this cache, in minutes rounded down.
+   */
+  getAgeMinutes(): number {
+    return Math.floor((Date.now() - this.time) / ONE_MINUTE_MS)
+  }
 
-/** Get the cached calendar body, or nothing if unset or expired. */
-async function getCachedCalendarBody(): Promise<string | null> {
-  const cacheAgeMinutes = (Date.now() - cachedCalendarTime) / ONE_MINUTE_MS
-  if (cacheAgeMinutes >= calendarCacheExpiration) {
-    // Cache invalidated by expiration time
-    return null
+  /**
+   * Check if this cache is expired.
+   * @returns `true` if expired, `false` otherwise.
+   */
+  isExpired(): boolean {
+    return this.getAgeMinutes() >= this.expirationTimeMinutes
   }
 
-  const calendarUrls = await (await getCalendarUrls()).join()
-  if (calendarUrls != cachedCalendarUrls) {
-    // Cache invalidated by changed URLs
-    return null
+  /**
+   * Check if this cache is invalidated by changed URLs.
+   * @param urls The current calendar URLs.
+   * @returns `true` if the URLs have changed, `false` otherwise.
+   */
+  isInvalidated(urls: string[]): boolean {
+    return this.urls.join() !== urls.join()
   }
 
-  return cachedCalendarBody
+  /**
+   * Get the cached calendar body if not stale.
+   * @returns The cached calendar body or nothing if stale.
+   */
+  async getCalendarBody(): Promise<string | null> {
+    if (cachedCalendar === null || cachedCalendar.isExpired()) {
+      return null
+    }
+
+    const calendarUrls = await getCalendarUrls()
+    if (cachedCalendar.isInvalidated(calendarUrls)) {
+      return null
+    }
+
+    return cachedCalendar.calendarBody
+  }
 }
 
-/** Save a calendar body to the cache and save the cached time. */
+let cachedCalendar: CachedCalendar | null = null
+
+/** Save a calendar body to the cache. */
 async function cacheCalendarBody(calendarBody: string) {
-  cachedCalendarBody = calendarBody
-  cachedCalendarTime = Date.now()
-  cachedCalendarUrls = (await getCalendarUrls()).join()
+  const calendarUrls = await getCalendarUrls()
+  cachedCalendar = new CachedCalendar(calendarBody, calendarUrls)
 }
 
+/**
+ * Get the calendar URLs from the database. Calendar links are all links that
+ * start with `_kalender`.
+ * @returns A string array containing the URLs.
+ */
 async function getCalendarUrls(): Promise<string[]> {
   const calendarLinks = await prisma.links.findMany({
     where: {
@@ -65,30 +125,44 @@ async function getCalendarUrls(): Promise<string[]> {
   })
 
   const calendarUrls = calendarLinks.map(link => link.url)
+  calendarUrls.forEach((url, index) => {
+    if (calendarUrls.lastIndexOf(url) !== index) {
+      throw new Error('Links contain duplicate calendar URLs. Calendar events must be unique.')
+    }
+  })
 
   return calendarUrls
 }
 
+/**
+ * Fetch and parse a calendar hosted at `url`.
+ * @param url The URL to fetch the calendar from.
+ * @throws If the calendar cannot be fetched.
+ * @throws If parsing the calendar text failed.
+ * @returns The parsed calendar after fetching the URL.
+ */
 async function fetchCalendar(url: string): Promise<Calendar> {
   return fetch(url)
-  .then(response => {
-    if (!response.ok)
-      throw new Error(`Failed fetching calendar: ${response}`)
-    return response.text()
-  })
-  .then(text => {
-    return parseCalendar(text)
-  })
-  .catch(reason => {
-    throw reason
-  })
+    .then(response => {
+      if (!response.ok)
+        throw new Error(`Failed fetching calendar: ${response}`)
+      return response.text()
+    })
+    .then(text => {
+      return parseCalendar(text)
+    })
+    .catch(reason => {
+      throw reason
+    })
 }
 
 /**
-* Merge multiple calendars together. The name will be taken from the primary calendar.
-* @param calendars The calendars to merge together, where the first is the primary calendar.
-* @throws If `calendars` is empty.
-*/
+ * Merge multiple calendars together. The name and other properties will be
+ * taken from the first calendar.
+ * @param calendars The calendars to merge together.
+ * @throws If `calendars` is empty.
+ * @returns The merged calendar.
+ */
 function mergeCalendars(calendars: Calendar[]): Calendar {
   if (calendars.length === 0)
     throw new Error('At least one calendar must be provided')
@@ -104,10 +178,14 @@ function mergeCalendars(calendars: Calendar[]): Calendar {
   return mergedCalendar
 }
 
-async function createMergedCalendar(
-  productId: string
-): Promise<Calendar> {
-  const calendar = await getCalendarUrls()
+/**
+ * Create a merged calendar from the calendar links in the database.
+ * @param productId The product id of the newly created calendar.
+ * @throws If the calendar could not be created.
+ * @returns A merged calendar generated from the links.
+ */
+async function createMergedCalendar(productId: string): Promise<Calendar> {
+  const calendar: Calendar = await getCalendarUrls()
     .then(urls =>
       Promise.all(
         urls.map(url => {
@@ -118,44 +196,56 @@ async function createMergedCalendar(
     .then(calendars => {
       const isCalendar = (
         maybeCalendar: Calendar | undefined
-      ): maybeCalendar is Calendar => calendar !== undefined
-      
+      ): maybeCalendar is Calendar => maybeCalendar !== undefined
+
       const filteredCalendars: Calendar[] = calendars.filter(isCalendar)
       return mergeCalendars(filteredCalendars)
     })
+    .catch(reason => {
+      throw reason
+    })
+
   calendar.setProductId(productId)
   return calendar
 }
 
 /**
  * Create a merged calendar, or return the cached calendar if it exists. And cache
  * it if creating a new one.
- * @param productId The product id of the calendar if creating a new one.
  * @returns The new merged calendar, or the cached calendar if it exists and is not expired.
  */
-async function createCalendarBodyWithCache(productId: string): Promise<string> {
-  const cached = await getCachedCalendarBody()
+async function getCalendarBodyWithCache(): Promise<string> {
+  const cached = await cachedCalendar?.getCalendarBody()
   if (cached) {
     return cached
   }
-  const mergedCalendar = await createMergedCalendar(productId)
-  const calendarBody =  mergedCalendar.serialize()
+
+  const productId = '-//Teknologsektionen Informationsteknik//nollk.it//SV'
+  const calendarBody = await createMergedCalendar(productId)
+    .then(calendar => calendar.serialize())
+    .catch(reason => {
+      throw new Error(`Failed to create calendar body: ${reason}`)
+    })
+
   cacheCalendarBody(calendarBody)
   return calendarBody
 }
 
 export default async function handler(
-  req: NextApiRequest,
-  res: NextApiResponse
+    req: NextApiRequest,
+    res: NextApiResponse
 ) {
-  const productId = '-//Teknologsektionen Informationsteknik//nollk.it//SV'
-  const calendarBody: string = await createCalendarBodyWithCache(productId)
-    .catch(reason => {
-      console.warn(`Failed to create merged calendar: ${reason}`)
-      return new Calendar(productId).serialize()
+  try {
+    const calendarBody = await getCalendarBodyWithCache()
+    res.setHeader('Content-Type', 'text/calendar')
+    res.setHeader('Content-Disposition', 'attachment; filename=schema.ics')
+    res.status(200).end(calendarBody)
+  } catch (e) {
+    res.status(500).json({
+      error: {
+        message: "Failed to get calendar content",
+        details: String(e)
+      }
     })
-  
-  res.setHeader('Content-Type', 'text/calendar')
-  res.setHeader('Content-Disposition', 'attachment; filename=schema.ics')
-  res.status(200).send(calendarBody)
+  }
 }