Source

Package Location

• Directorymodules

  • Directorycartographer

    • index.ts
    • types.ts

Dependencies

Result

Tracer

Note

Tracer is purly a type dependency, if you don’t want to include it just as a type dependency you can replace the import with the following:

type Logger = {
  error: (
    message: string,
    args?: {
      [key: string]: any
    },
  ) => void
}

Source Code

index.ts

import { Err, Try, TryAsync } from "@/modules/utility/result"
import type { Types } from "./types"

type SiteMapper = Map<string, DynamicMap | StaticMap>

export class Cartographer {
  #sitemap: SiteMapper = new Map()
  #config: Types.ConcertConfig

  constructor(config: Types.Config) {
    this.#config = {
      priorityFn: () => 0.7,
      defaultChangeFrequency: "weekly",
      defaultLastMod: new Date(),
      logger: {
        error: console.error,
      },
      urlsPerPage: 10_000,
      ...config,
    }
  }

  dynamic(key: string, { fetcher, counter }: Types.DynamicInput) {
    this.#sitemap.set(key, new DynamicMap(key, fetcher, counter, this.#config))
    return this
  }

  static(key: string, input: Types.StaticInput) {
    this.#sitemap.set(`${key}.xml`, new StaticMap(key, input, this.#config))
    return this
  }

  finalise() {
    return new CartographerToolbelt(this.#sitemap, this.#config)
  }
}

class CartographerToolbelt {
  #sitemap: SiteMapper
  #config: Types.ConcertConfig

  constructor(sitemap: SiteMapper, config: Types.ConcertConfig) {
    this.#sitemap = sitemap
    this.#config = config
  }

  #abort(
    ...args: Parameters<Types.ConcertConfig["logger"]["error"]>
  ): Response {
    this.#config.logger.error(args[0], args[1])

    return new Response("Not Found", {
      status: 404,
      headers: {
        "Content-Type": "text/plain",
      },
    })
  }

  #format(entries: Types.SitemapEntry[]): string[] {
    return entries.map((entry) => {
      const url = entry.url
      const slug = new URL(url).pathname

      const priority = entry.priority || this.#config.priorityFn(slug)
      let lastModified = entry.lastModified || this.#config.defaultLastMod
      lastModified =
        typeof lastModified === "string"
          ? lastModified
          : lastModified.toISOString()

      const root = [
        `<loc>${entry.url}</loc>`,
        `<priority>${priority}</priority>`,
        `<changefreq>${entry.changeFrequency || this.#config.defaultChangeFrequency}</changefreq>`,
        `<lastmod>${lastModified}</lastmod>`,
      ]

      return `<url>${root.join("")}</url>`
    })
  }

  async $survey(): Promise<Response> {
    const promises: Promise<string[]>[] = []
    for (const map of this.#sitemap.values()) {
      promises.push(map.$list())
    }

    const sitemaps = await Promise.all(promises)

    const xml = [
      '<?xml version="1.0" encoding="UTF-8"?>',
      '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
      ...sitemaps.flat().map((url) => `<sitemap><loc>${url}</loc></sitemap>`),
      "</sitemapindex>",
    ].join("")

    return new Response(xml, {
      headers: {
        "Content-Type": "application/xml",
      },
    })
  }

  async $draw(_: unknown, data: Types.Segment): Promise<Response> {
    const params = await data.params
    const map = this.#sitemap.get(params.key)
    if (!map) {
      return this.#abort(`${params.key} is not a registered sitemap`)
    }

    // prettier-ignore
    const entries = map instanceof StaticMap
        ? Try(() => map.$draw())()
        : await TryAsync(() => map.$draw(params))()

    if (Err(entries)) {
      return this.#abort(`Unable to generate entries for ${params.key}`, {
        error: entries,
      })
    }

    const body = this.#format(entries)

    const xml = [
      '<?xml version="1.0" encoding="UTF-8"?>',
      '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">',
      body,
      "</urlset>",
    ].join("")

    return new Response(xml, {
      headers: {
        "Content-Type": "application/xml",
      },
    })
  }
}

class DynamicMap {
  #key: string
  #fetcher: Types.DynamicFetcher
  #config: Types.ConcertConfig
  #counter: Types.DynamicCounter

  constructor(
    key: string,
    fetcher: Types.DynamicFetcher,
    counter: Types.DynamicCounter,
    config: Types.ConcertConfig,
  ) {
    this.#key = key
    this.#fetcher = fetcher
    this.#config = config
    this.#counter = counter
  }

  extractPageId(id: string) {
    const withoutExtension = id.replace(/\.xml$/, "")
    const asNumber = Number(withoutExtension)

    if (Number.isNaN(asNumber)) {
      throw new Error("Invalid page id, must be a number")
    }

    return Math.floor(asNumber)
  }

  async $draw(
    params: Awaited<Types.Segment["params"]>,
  ): Promise<Types.SitemapEntry[]> {
    if (!params.page || params.page.length !== 1) {
      throw new Error("Dynamic sitemaps require a page parameter")
    }
    const page = this.extractPageId(params.page[0])

    const count = await this.#counter()
    const result = await TryAsync(this.#fetcher)(
      page,
      count,
      this.#config.urlsPerPage,
    )

    if (Err(result)) throw result

    return result.map((value) => {
      value.url = new URL(value.url, this.#config.domain).href
      return value
    })
  }

  async $list(): Promise<string[]> {
    const count = await this.#counter()
    if (count === 0) return []
    const pages = Math.ceil(count / this.#config.urlsPerPage)

    return Array.from({ length: pages }).map((_, index) => {
      return `${this.#config.domain}/sitemap/${this.#key}/${index}.xml`
    })
  }
}

class StaticMap {
  #key: string
  #input: Types.StaticInput
  #config: Types.ConcertConfig

  constructor(
    key: string,
    input: Types.StaticInput,
    config: Types.ConcertConfig,
  ) {
    this.#key = key
    this.#input = input
    this.#config = config
  }

  $draw(): Types.SitemapEntry[] {
    return this.#input.map((value) => {
      return typeof value === "string"
        ? { url: new URL(value, this.#config.domain).href }
        : value
    })
  }

  async $list(): Promise<string[]> {
    return [`${this.#config.domain}/sitemap/${this.#key}.xml`]
  }
}

types.ts

import type { Logger } from "@/modules/utility/trace"

export namespace Types {
  export type PriorityFn = (url: string) => number
  export type ChangeFrequency =
    | "always"
    | "hourly"
    | "daily"
    | "weekly"
    | "monthly"
    | "yearly"
    | "never"
  export type LastMod = string | Date

  export type SitemapEntry = {
    url: string
    lastModified?: LastMod
    changeFrequency?: ChangeFrequency
    priority?: ReturnType<PriorityFn>
  }

  export type StaticInput = (string | SitemapEntry)[]

  export type DynamicFetcher = (
    /** This is the sitemap page you are on, it is 0 based */
    page: number,
    /** Return value of the `DynamicCounter` */
    count: number,
    /**
     * This is the limit of the number of urls you can have for a given page.
     *
     * You will need to take this into account for your generation. If the
     * limit is 1_000 and your API only allows for 100 records per fetch,
     * then per page, you will need to make 10 requests to fill up the
     * current page of records.
     *
     * You can multiple this by the `page` to get your initial `offset`
     * or `skip` value.
     */
    urlsPerPage: number,
  ) => Promise<SitemapEntry[]>
  export type DynamicCounter = () => Promise<number>

  export type DynamicInput = {
    fetcher: DynamicFetcher
    counter: DynamicCounter
  }

  export type Segment = {
    params: Promise<{
      key: string
      page?: string[]
    }>
  }

  type NotNill<T> = T extends null | undefined ? never : T

  type Primitive =
    | undefined
    | null
    | boolean
    | string
    | number
    | Function
    | Date

  type DeepRequired<T> = T extends Primitive
    ? NotNill<T>
    : {
        [P in keyof T]-?: T[P] extends Array<infer U>
          ? Array<DeepRequired<U>>
          : T[P] extends ReadonlyArray<infer U2>
            ? DeepRequired<U2>
            : DeepRequired<T[P]>
      }

  export type Config = {
    domain: string
    urlsPerPage?: number
    priorityFn?: PriorityFn
    defaultChangeFrequency?: ChangeFrequency
    defaultLastMod?: LastMod
    logger?: Pick<Logger, "error">
  }

  export type ConcertConfig = DeepRequired<Config>
}