Allow customization of the PageFunction return type

Author: bcomnes

index.js

@@ -30,27 +30,28 @@ import { DomStackAggregateError } from './lib/helpers/dom-stack-aggregate-error.
  */
 
 /**
- * @template {Record<string, any>} T
+ * @template {Record<string, any>} T - The type of variables passed to the layout function
  * @typedef {LayoutFunction<T>} LayoutFunction
  */
 
 /**
- * @template {Record<string, any>} T
+ * @template {Record<string, any>} T - The type of variables for the post vars function
  * @typedef {PostVarsFunction<T>} PostVarsFunction
  */
 
 /**
- * @template {Record<string, any>} T
- * @typedef {PageFunction<T>} PageFunction
+ * @template {Record<string, any>} T - The type of variables passed to the page function
+ * @template [U=any] U - The return type of the page function (defaults to any)
+ * @typedef {PageFunction<T, U>} PageFunction
  */
 
 /**
- * @template {Record<string, any>} T
+ * @template {Record<string, any>} T - The type of variables for the template function
  * @typedef {TemplateFunction<T>} TemplateFunction
  */
 
 /**
- * @template {Record<string, any>} T
+ * @template {Record<string, any>} T - The type of variables for the template async iterator
  * @typedef {TemplateAsyncIterator<T>} TemplateAsyncIterator
  */
 
@@ -69,7 +70,7 @@ const DEFAULT_IGNORES = /** @type {const} */ ([
 ])
 
 /**
- * @template {DomStackOpts} [CurrentOpts=DomStackOpts]
+ * @template {DomStackOpts} [CurrentOpts=DomStackOpts] - The type of options for the DomStack instance
  */
 export class DomStack {
   /** @type {string} */ #src = ''

lib/build-pages/page-builders/html/index.js

@@ -8,8 +8,8 @@ import Handlebars from 'handlebars'
 
 /**
  * Build all of the bundles using esbuild.
- * @template {Record<string, any>} T
- * @type {PageBuilderType<T>}
+ * @template {Record<string, any>} T - The type of variables for the page
+ * @type {PageBuilderType<T, string>}
  */
 export async function htmlBuilder ({ pageInfo }) {
   assert(pageInfo.type === 'html', 'html builder requires a "html" page type')

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

@@ -6,8 +6,9 @@ import assert from 'node:assert'
 
 /**
  * Build all of the bundles using esbuild.
- * @template {Record<string, any>} T
- * @type {PageBuilderType<T>}
+ * @template {Record<string, any>} T - The type of variables for the page
+ * @template [U=any] U - The return type of the pageLayout function
+ * @type {PageBuilderType<T, U>}
  */
 export async function jsBuilder ({ pageInfo }) {
   assert(pageInfo.type === 'js', 'js page builder requires "js" page type')

lib/build-pages/page-builders/md/index.js

@@ -13,8 +13,8 @@ let md = null
 
 /**
  * Build all of the bundles using esbuild.
- * @template {Record<string, any>} T
- * @type {PageBuilderType<T>}
+ * @template {Record<string, any>} T - The type of variables for the page
+ * @type {PageBuilderType<T, string>}
  */
 export async function mdBuilder ({ pageInfo, options }) {
   assert(pageInfo.type === 'md', 'md builder requires an "md" page type')

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

@@ -20,7 +20,8 @@ import { writeFile, mkdir } from 'fs/promises'
  * pageLayout functions Can be used to type a name.layout.js file
  *
  * @async
- * @template {Record<string, any>} T
+ * @template {Record<string, any>} T - The type of variables passed to the page function
+ * @template [U=any] U - The return type of the page function (defaults to any)
  * @callback PageFunction
  * @param {object} params - The parameters for the pageLayout.
  * @param {T} params.vars - All default, global, layout, page, and builder vars shallow merged.
@@ -29,24 +30,26 @@ import { writeFile, mkdir } from 'fs/promises'
  * @param {PageInfo} params.page - Info about the current page
  * @param {PageData<T>[]} 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<any> | any} The rendered inner page thats compatible with its matched layout
+ * @returns {Promise<U> | U} The rendered inner page thats compatible with its matched layout
  */
 
 /**
- * @template {Record<string, any>} T
+ * @template {Record<string, any>} T - The type of variables for the page
+ * @template [U=any] U - The return type of the pageLayout function
  * @typedef PageBuilderResult
  * @property {object} vars - Any variables resolved by the builder
- * @property {PageFunction<T>} pageLayout - The function that returns the rendered page
+ * @property {PageFunction<T, U>} pageLayout - The function that returns the rendered page
  */
 
 /**
- * @template {Record<string, any>} T
+ * @template {Record<string, any>} T - The type of variables for the page
+ * @template [U=any] U - The return type of the pageLayout function
  * @callback PageBuilderType
  *
  * @param {object} params
  * @param {PageInfo} params.pageInfo
  * @param {BuilderOptions} [params.options]
- * @returns {Promise<PageBuilderResult<T>>} - The results of the build step.
+ * @returns {Promise<PageBuilderResult<T, U>>} - The results of the build step.
  */
 
 /**

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

@@ -14,7 +14,7 @@ import { writeFile, mkdir } from 'fs/promises'
 /**
  * Callback for rendering a template.
  *
- * @template {Record<string, any>} T
+ * @template {Record<string, any>} T - The type of variables for the template
  * @callback TemplateFunction
  * @param {object} params - The parameters for the template.
  * @param {T} params.vars - All of the site globalVars.
@@ -25,13 +25,13 @@ import { writeFile, mkdir } from 'fs/promises'
  */
 
 /**
- * @template {Record<string, any>} T
+ * @template {Record<string, any>} T - The type of variables for the template function parameters
  * @typedef {Parameters<TemplateFunction<T>>} TemplateFunctionParams
 */
 
 /**
  * Callback for rendering a template with an async iterator.
- * @template T
+ * @template T - The type of variables for the template async iterator
  * @callback TemplateAsyncIterator
  * @param {TemplateFunctionParams<T>[0]} params - Parameters of the template function.
  * @returns {AsyncIterable<TemplateOutputOverride>}
@@ -47,7 +47,7 @@ import { writeFile, mkdir } from 'fs/promises'
 
 /**
  * The template builder renders templates agains the globalVars variables
- * @template {Record<string, any>} T
+ * @template {Record<string, any>} T - The type of global variables for the template builder
  * @param {object}  params
  * @param  {string} params.src        - The src path of the site build.
  * @param  {string} params.dest       - The dest path of the site build.

lib/build-pages/page-data.js

@@ -18,7 +18,7 @@ import pretty from 'pretty'
  *
  * @async
  * @function
- * @template T
+ * @template T - The type of variables for the layout
  * @param {string} layoutPath - The string path to the layout ESM module.
  * @returns {Promise<LayoutFunction<T>>} The resolved layout exported as default from the module.
  */
@@ -31,7 +31,7 @@ export async function resolveLayout (layoutPath) {
 /**
   * Callback for rendering a layout.
   *
-  * @template T
+  * @template T - The type of variables passed to the layout function
   * @callback LayoutFunction
   * @param {object} params - The parameters for the layout.
   * @param {T} params.vars - All default, global, layout, page, and builder vars shallow merged.
@@ -48,7 +48,7 @@ export async function resolveLayout (layoutPath) {
   * postVars functions Can be used to generate page vars but access all page data
   *
   * @async
-  * @template {Record<string, any>} T
+  * @template {Record<string, any>} T - The type of variables for the page
   * @callback PostVarsFunction
   * @param {object} params - The parameters for the pageLayout.
   * @param {T} params.vars - All default, global, layout, page, and builder vars shallow merged.
@@ -62,7 +62,7 @@ export async function resolveLayout (layoutPath) {
 
 /**
  * Represents the data for a page.
- * @template {Record<string, any>} T
+ * @template {Record<string, any>} T - The type of variables for the page data
  */
 export class PageData {
   /** @type {PageInfo} */ pageInfo