Enable customization of LayoutFunction types

Author: bcomnes

index.js

@@ -31,12 +31,16 @@ import { DomStackAggregateError } from './lib/helpers/dom-stack-aggregate-error.
 
 /**
  * @template {Record<string, any>} T - The type of variables passed to the layout function
- * @typedef {LayoutFunction<T>} LayoutFunction
+ * @template [U=any] U - The return type of the page function (defaults to any)
+ * @template [V=string] V - The return type of the layout function (defaults to string)
+ * @typedef {LayoutFunction<T, U, V>} LayoutFunction
  */
 
 /**
  * @template {Record<string, any>} T - The type of variables for the post vars function
- * @typedef {PostVarsFunction<T>} PostVarsFunction
+ * @template [U=any] U - The return type of the page function (defaults to any)
+ * @template [V=string] V - The return type of the layout function (defaults to string)
+ * @typedef {PostVarsFunction<T, U, V>} PostVarsFunction
  */
 
 /**

lib/build-pages/index.js

@@ -37,9 +37,11 @@ const __dirname = import.meta.dirname
  */
 
 /**
- * @template T
+ * @template T - The type of variables for the layout
+ * @template [U=any] U - The return type of the page function (defaults to any)
+ * @template [V=string] V - The return type of the layout function (defaults to string)
  * @typedef ResolvedLayout
- * @property {LayoutFunction<T>} render - The layout function
+ * @property {LayoutFunction<T, U, V>} render - The layout function
  * @property {string} name - The name of the layout
  * @property {string | null} layoutStylePath - The string path to the layout style
  * @property {string | null} layoutClientPath - The string path to the layout client
@@ -126,7 +128,7 @@ export async function buildPagesDirect (src, dest, siteData, _opts) {
     }),
   ])
 
-  /** @type {ResolvedLayout<object>[]} */
+  /** @type {ResolvedLayout<object, any, string>[]} */
   const resolvedLayoutResults = await pMap(Object.values(siteData.layouts), async (layout) => {
     const render = await resolveLayout(layout.filepath)
     return {

lib/build-pages/page-builders/page-writer.js

@@ -13,7 +13,9 @@ import { writeFile, mkdir } from 'fs/promises'
 
 /**
  * @template {Record<string, any>} T
- * @typedef {PageData<T>} PageData
+ * @template [U=any] U - The return type of the page function (defaults to any)
+ * @template [V=string] V - The return type of the layout function (defaults to string)
+ * @typedef {PageData<T, U, V>} PageData
  */
 
 /**
@@ -28,7 +30,7 @@ import { writeFile, mkdir } from 'fs/promises'
  * @param {string[]} [params.scripts] - Array of script URLs to include.
  * @param {string[]} [params.styles] - Array of stylesheet URLs to include.
  * @param {PageInfo} params.page - Info about the current page
- * @param {PageData<T>[]} params.pages - An array of info about every page
+ * @param {PageData<T, U, string>[]} params.pages - An array of info about every page
  * @param {Object<string, string>} [params.workers] - Map of worker names to their output paths
  * @returns {Promise<U> | U} The rendered inner page thats compatible with its matched layout
  */
@@ -55,11 +57,13 @@ import { writeFile, mkdir } from 'fs/promises'
 /**
  * Handles rendering and writing a page to disk
  * @template {Record<string, any>} T
+ * @template [U=any] U - The return type of the page function (defaults to any)
+ * @template [V=string] V - The return type of the layout function (defaults to string)
  * @param {object} params
  * @param {string} params.src   - The src folder.
  * @param {string} params.dest  - The dest folder.
- * @param {PageData<T>} params.page  - The PageInfo object of the current page
- * @param {PageData<T>[]} params.pages - The PageInfo[] array of all pages
+ * @param {PageData<T, U, V>} params.page  - The PageInfo object of the current page
+ * @param {PageData<T, U, V>[]} params.pages - The PageInfo[] array of all pages
  */
 export async function pageWriter ({
   dest,

lib/build-pages/page-builders/template-builder.js

@@ -19,7 +19,7 @@ import { writeFile, mkdir } from 'fs/promises'
  * @param {object} params - The parameters for the template.
  * @param {T} params.vars - All of the site globalVars.
  * @param {TemplateInfo} params.template - Info about the current template
- * @param {PageData<T>[]} params.pages - An array of info about every page
+ * @param {PageData<T, any, string>[]} params.pages - An array of info about every page
  * @returns {Promise<string | TemplateOutputOverride | TemplateOutputOverride[]>}
  *  } - The results of a template build
  */
@@ -53,7 +53,7 @@ import { writeFile, mkdir } from 'fs/promises'
  * @param  {string} params.dest       - The dest path of the site build.
  * @param  {T} params.globalVars - The resolvedGlobal vars object.
  * @param  {TemplateInfo} params.template   - The TemplateInfo of the template.
- * @param  {PageData<T>[]} params.pages      - The array of PageData object.
+ * @param  {PageData<T, any, string>[]} params.pages      - The array of PageData object.
  */
 export async function templateBuilder ({
   dest,

lib/build-pages/page-data.js

@@ -19,8 +19,10 @@ import pretty from 'pretty'
  * @async
  * @function
  * @template T - The type of variables for the layout
+ * @template [U=any] U - The return type of the page function (defaults to any)
+ * @template [V=string] V - The return type of the layout function (defaults to string)
  * @param {string} layoutPath - The string path to the layout ESM module.
- * @returns {Promise<LayoutFunction<T>>} The resolved layout exported as default from the module.
+ * @returns {Promise<LayoutFunction<T, U, V>>} The resolved layout exported as default from the module.
  */
 export async function resolveLayout (layoutPath) {
   const { default: layout } = await import(layoutPath)
@@ -32,41 +34,47 @@ export async function resolveLayout (layoutPath) {
   * Callback for rendering a layout.
   *
   * @template T - The type of variables passed to the layout function
+  * @template [U=any] U - The return type of the page function (defaults to any)
+  * @template [V=string] V - The return type of the layout function (defaults to string)
   * @callback LayoutFunction
   * @param {object} params - The parameters for the layout.
   * @param {T} params.vars - All default, global, layout, page, and builder vars shallow merged.
   * @param {string[]} [params.scripts] - Array of script URLs to include.
   * @param {string[]} [params.styles] - Array of stylesheet URLs to include.
   * @param {any} params.children - The children content, either as a string or a render function.
   * @param {PageInfo} params.page - Info about the current page
-  * @param {PageData<T>[]} params.pages - An array of info about every page
+  * @param {PageData<T, U, V>[]} params.pages - An array of info about every page
   * @param {Object<string, string>} [params.workers] - Map of worker names to their output paths
-  * @returns {Promise<string> | string} The rendered HTML string.
+  * @returns {Promise<V> | V} The rendered content.
   */
 
 /**
   * postVars functions Can be used to generate page vars but access all page data
   *
   * @async
   * @template {Record<string, any>} T - The type of variables for the page
+  * @template [U=any] U - The return type of the page function (defaults to any)
+  * @template [V=string] V - The return type of the layout function (defaults to string)
   * @callback PostVarsFunction
   * @param {object} params - The parameters for the pageLayout.
   * @param {T} params.vars - All default, global, layout, page, and builder vars shallow merged.
   * @param {string[]} [params.scripts] - Array of script URLs to include.
   * @param {string[]} [params.styles] - Array of stylesheet URLs to include.
   * @param {PageInfo} params.page - Info about the current page
-  * @param {PageData<T>[]} params.pages - An array of info about every page
+  * @param {PageData<T, U, V>[]} params.pages - An array of info about every page
   * @param {Object<string, string>} [params.workers] - Map of worker names to their output paths
   * @returns {Promise<T>} The rendered postVars
   */
 
 /**
  * Represents the data for a page.
  * @template {Record<string, any>} T - The type of variables for the page data
+ * @template [U=any] U - The return type of the page function (defaults to any)
+ * @template [V=string] V - The return type of the layout function (defaults to string)
  */
 export class PageData {
   /** @type {PageInfo} */ pageInfo
-  /** @type {ResolvedLayout<T> | null | undefined} */ layout
+  /** @type {ResolvedLayout<T, U, V> | null | undefined} */ layout
   /** @type {object} */ globalVars
   /** @type {object?} */ pageVars = null
   /** @type {function?} */ postVars = null
@@ -139,7 +147,7 @@ export class PageData {
   }
 
   /**
-   * @type {PostVarsFunction<T>}
+   * @type {PostVarsFunction<T, U, V>}
    */
   async #renderPostVars ({ vars, styles, scripts, pages, page, workers }) {
     if (!this.#initialized) throw new Error('Initialize PageData before accessing renderPostVars')
@@ -163,7 +171,7 @@ export class PageData {
   /**
    * [init description]
    * @param  {object} params - Parameters required to initialize
-   * @param  {Record<string,ResolvedLayout<T>>} params.layouts - The array of ResolvedLayouts
+   * @param  {Record<string,ResolvedLayout<T, U, V>>} params.layouts - The array of ResolvedLayouts
    */
   async init ({ layouts }) {
     if (this.#initialized) return
@@ -232,7 +240,7 @@ export class PageData {
   /**
    * Render the inner contents of a page.
    * @param  {object} params The params required to render the page
-   * @param  {PageData<T>[]} params.pages An array of initialized PageDatas.
+   * @param  {PageData<T, U, V>[]} params.pages An array of initialized PageDatas.
    */
   async renderInnerPage ({ pages }) {
     if (!this.#initialized) throw new Error('Must be initialized before rendering inner pages')
@@ -248,7 +256,7 @@ export class PageData {
   /**
    * Render the full contents of a page with its layout
    * @param  {object} params The params required to render the page
-   * @param  {PageData<T>[]} params.pages An array of initialized PageDatas.
+   * @param  {PageData<T, U, V>[]} params.pages An array of initialized PageDatas.
    */
   async renderFullPage ({ pages }) {
     if (!this.#initialized) throw new Error('Must be initialized before rendering full pages')