Add Async type variants for the various layout and page functions

Author: bcomnes

.gitignore

@@ -10,3 +10,5 @@ coverage
 
 *.d.ts
 *.d.ts.map
+!types/**/*.d.ts
+!types/**/*.d.ts.map

README.md

@@ -1183,13 +1183,18 @@ You can use `domstack`'s built-in types to strongly type your layout, page, and
 ```ts
 import type {
   LayoutFunction,
+  AsyncLayoutFunction,
   PostVarsFunction,
+  AsyncPostVarsFunction,
   PageFunction,
+  AsyncPageFunction,
   TemplateFunction,
   TemplateAsyncIterator
 } from '@domstack/static'
 ```
 
+> **Note:** All function types have both synchronous and asynchronous variants (e.g., `LayoutFunction` and `AsyncLayoutFunction`). Use the async variants when your function is an `async` function.
+
 They are all generic and accept a variable template that you can develop and share between files.
 
 #### Advanced Type Parameters for PageFunction and LayoutFunction

index.js

@@ -1,8 +1,8 @@
 /**
  * @import { DomStackOpts as DomStackOpts, Results } from './lib/builder.js'
  * @import { FSWatcher, Stats } from 'node:fs'
- * @import { PostVarsFunction, LayoutFunction } from './lib/build-pages/page-data.js'
- * @import { PageFunction } from './lib/build-pages/page-builders/page-writer.js'
+ * @import { PostVarsFunction, AsyncPostVarsFunction, AsyncLayoutFunction, LayoutFunction } from './lib/build-pages/page-data.js'
+ * @import { PageFunction, AsyncPageFunction } from './lib/build-pages/page-builders/page-writer.js'
  * @import { TemplateFunction } from './lib/build-pages/page-builders/template-builder.js'
  * @import { TemplateAsyncIterator } from './lib/build-pages/page-builders/template-builder.js'
  * @import { TemplateOutputOverride } from './lib/build-pages/page-builders/template-builder.js'
@@ -36,19 +36,39 @@ import { DomStackAggregateError } from './lib/helpers/dom-stack-aggregate-error.
  * @typedef {LayoutFunction<Vars, PageReturn, LayoutReturn>} LayoutFunction
  */
 
+/**
+ * @template {Record<string, any>} Vars - The type of variables passed to the async layout function
+ * @template [PageReturn=any] PageReturn - The return type of the page function (defaults to any)
+ * @template [LayoutReturn=string] LayoutReturn - The return type of the layout function (defaults to string)
+ * @typedef {AsyncLayoutFunction<Vars, PageReturn, LayoutReturn>} AsyncLayoutFunction
+ */
+
 /**
  * @template {Record<string, any>} Vars - The type of variables for the post vars function
  * @template [PageReturn=any] PageReturn - The return type of the page function (defaults to any)
  * @template [LayoutReturn=string] LayoutReturn - The return type of the layout function (defaults to string)
  * @typedef {PostVarsFunction<Vars, PageReturn, LayoutReturn>} PostVarsFunction
  */
 
+/**
+ * @template {Record<string, any>} Vars - The type of variables for the async post vars function
+ * @template [PageReturn=any] PageReturn - The return type of the page function (defaults to any)
+ * @template [LayoutReturn=string] LayoutReturn - The return type of the layout function (defaults to string)
+ * @typedef {AsyncPostVarsFunction<Vars, PageReturn, LayoutReturn>} AsyncPostVarsFunction
+ */
+
 /**
  * @template {Record<string, any>} Vars - The type of variables passed to the page function
  * @template [PageReturn=any] PageReturn - The return type of the page function (defaults to any)
  * @typedef {PageFunction<Vars, PageReturn>} PageFunction
  */
 
+/**
+ * @template {Record<string, any>} Vars - The type of variables passed to the async page function
+ * @template [PageReturn=any] PageReturn - The return type of the page function (defaults to any)
+ * @typedef {AsyncPageFunction<Vars, PageReturn>} AsyncPageFunction
+ */
+
 /**
  * @template {Record<string, any>} Vars - The type of variables for the template function
  * @typedef {TemplateFunction<Vars>} TemplateFunction

lib/build-pages/index.js

@@ -1,7 +1,7 @@
 /**
  * @import { BuilderOptions } from './page-builders/page-writer.js'
  * @import { BuildStep } from '../builder.js'
- * @import { LayoutFunction } from './page-data.js'
+ * @import { InternalLayoutFunction } from './page-data.js'
  */
 
 import { Worker } from 'worker_threads'
@@ -37,11 +37,11 @@ const __dirname = import.meta.dirname
  */
 
 /**
- * @template T - The type of variables for the layout
+ * @template {Record<string, any>} 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, U, V>} render - The layout function
+ * @property {InternalLayoutFunction<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

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

@@ -19,27 +19,53 @@ import { writeFile, mkdir } from 'fs/promises'
  */
 
 /**
- * pageLayout functions Can be used to type a name.layout.js file
+ * Common parameters for page functions.
+ *
+ * @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 {object} PageFunctionParams
+ * @property {T} vars - All default, global, layout, page, and builder vars shallow merged.
+ * @property {string[]} [scripts] - Array of script URLs to include.
+ * @property {string[]} [styles] - Array of stylesheet URLs to include.
+ * @property {PageInfo} page - Info about the current page
+ * @property {PageData<T, U, string>[]} pages - An array of info about every page
+ * @property {Object<string, string>} [workers] - Map of worker names to their output paths
+ */
+
+/**
+ * Synchronous page function for rendering a page layout.
  *
  * @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.
- * @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, 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
+ * @param {PageFunctionParams<T, U>} params - The parameters for the pageLayout.
+ * @returns {U | Promise<U>} The rendered inner page thats compatible with its matched layout
+ */
+
+/**
+ * Asynchronous page function for rendering a page layout.
+ *
+ * @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 AsyncPageFunction
+ * @param {PageFunctionParams<T, U>} params - The parameters for the pageLayout.
+ * @returns {Promise<U>} The rendered inner page thats compatible with its matched layout
+ */
+
+/**
+ * pageLayout functions can be used to type a name.layout.js file (can be sync or async).
+ *
+ * @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> | AsyncPageFunction<T, U>} InternalPageFunction
  */
 
 /**
  * @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, U>} pageLayout - The function that returns the rendered page
+ * @property {InternalPageFunction<T, U>} pageLayout - The function that returns the rendered page
  */
 
 /**

lib/build-pages/page-data.js

@@ -17,11 +17,11 @@ import pretty from 'pretty'
  * Resolves a layout from an ESM module.
  *
  * @function
- * @template T - The type of variables for the layout
+ * @template {Record<string, any>} 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, U, V>>} The resolved layout exported as default from the module.
+ * @returns {Promise<InternalLayoutFunction<T, U, V>>} The resolved layout exported as default from the module.
  */
 export async function resolveLayout (layoutPath) {
   const { default: layout } = await import(layoutPath)
@@ -30,40 +30,98 @@ export async function resolveLayout (layoutPath) {
 }
 
 /**
-  * Callback for rendering a layout.
+  * Common parameters for layout functions.
   *
-  * @template T - The type of variables passed to the layout function
+  * @template {Record<string, any>} 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)
+  * @typedef {object} LayoutFunctionParams
+  * @property {T} vars - All default, global, layout, page, and builder vars shallow merged.
+  * @property {string[]} [scripts] - Array of script URLs to include.
+  * @property {string[]} [styles] - Array of stylesheet URLs to include.
+  * @property {U} children - The children content, either as a string or a render function.
+  * @property {PageInfo} page - Info about the current page
+  * @property {PageData<T, U, V>[]} pages - An array of info about every page
+  * @property {Object<string, string>} [workers] - Map of worker names to their output paths
+  */
+
+/**
+  * Synchronous callback for rendering a layout.
+  *
+  * @template {Record<string, any>} 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 {U} 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, 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<V> | V} The rendered content.
+  * @param {LayoutFunctionParams<T, U, V>} params - The parameters for the layout.
+  * @returns {V | Promise<V>} The rendered content.
+  */
+
+/**
+  * Asynchronous callback for rendering a layout.
+  *
+  * @template {Record<string, any>} 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 AsyncLayoutFunction
+  * @param {LayoutFunctionParams<T, U, V>} params - The parameters for the layout.
+  * @returns {Promise<V>} The rendered content.
+  */
+
+/**
+  * Callback for rendering a layout (can be sync or async).
+  *
+  * @template {Record<string, any>} 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)
+  * @typedef {LayoutFunction<T, U, V> | AsyncLayoutFunction<T, U, V>} InternalLayoutFunction
   */
 
 /**
-  * postVars functions Can be used to generate page vars but access all page data
+  * Common parameters for postVars functions.
+  *
+  * @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)
+  * @typedef {object} PostVarsFunctionParams
+  * @property {T} vars - All default, global, layout, page, and builder vars shallow merged.
+  * @property {string[]} [scripts] - Array of script URLs to include.
+  * @property {string[]} [styles] - Array of stylesheet URLs to include.
+  * @property {PageInfo} page - Info about the current page
+  * @property {PageData<T, U, V>[]} pages - An array of info about every page
+  * @property {Object<string, string>} [workers] - Map of worker names to their output paths
+  */
+
+/**
+  * Synchronous postVars function to generate page vars with access to all page data.
   *
   * @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, 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
+  * @param {PostVarsFunctionParams<T, U, V>} params - The parameters for the postVars function.
+  * @returns {T | Promise<T>} The rendered postVars
+  */
+
+/**
+  * Asynchronous postVars function to generate page vars with access to all page data.
+  *
+  * @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 AsyncPostVarsFunction
+  * @param {PostVarsFunctionParams<T, U, V>} params - The parameters for the postVars function.
   * @returns {Promise<T>} The rendered postVars
   */
 
+/**
+  * postVars functions can be used to generate page vars but access all page data (can be sync or 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)
+  * @typedef {PostVarsFunction<T, U, V> | AsyncPostVarsFunction<T, U, V>} InternalPostVarsFunction
+  */
+
 /**
  * Represents the data for a page.
  * @template {Record<string, any>} T - The type of variables for the page data
@@ -79,7 +137,7 @@ export class PageData {
   /** @type {object?} */ builderVars = null
   /** @type {string[]} */ styles = []
   /** @type {string[]} */ scripts = []
-  /** @type {WorkerFiles|undefined} */ workerFiles = undefined
+  /** @type {WorkerFiles} */ workerFiles = {}
   /** @type {boolean} */ #initialized = false
   /** @type {T?} */ #renderedPostVars = null
   /** @type {string?} */ #defaultStyle = null
@@ -138,14 +196,14 @@ export class PageData {
 
   /**
    * Access web worker file paths associated with this page
-   * @return {WorkerFiles|undefined} Map of worker names to their output paths
+   * @return {WorkerFiles} Map of worker names to their output paths
    */
   get workers () {
     return this.workerFiles
   }
 
   /**
-   * @type {PostVarsFunction<T, U, V>}
+   * @type {AsyncPostVarsFunction<T, U, V>}
    */
   async #renderPostVars ({ vars, styles, scripts, pages, page, workers }) {
     if (!this.#initialized) throw new Error('Initialize PageData before accessing renderPostVars')
@@ -218,7 +276,6 @@ export class PageData {
     // Initialize web workers if they exist
     if (pageInfo.workers) {
       /** @type {WorkerFiles} */
-      this.workerFiles = {}
       for (const [workerName, workerFile] of Object.entries(pageInfo.workers)) {
         if (workerFile.outputRelname) {
           this.workerFiles[workerName] = `./${workerFile.outputName}`

lib/defaults/default.root.layout.js

@@ -1,5 +1,5 @@
 /**
- * @import { LayoutFunction } from '../build-pages/page-data.js'
+ * @import { LayoutFunction } from '../../index.js'
  * @import { VNode } from 'preact'
  */
 import { html } from 'htm/preact'

test-cases/general-features/src/blog/page.js

@@ -2,7 +2,7 @@ import { html } from 'htm/preact'
 import { dirname, basename } from 'node:path'
 
 /**
- * @type {import('../../../../index.js').LayoutFunction<{}>}
+ * @type {import('../../../../index.js').InternalLayoutFunction<{}>}
  */
 export default async function blogIndex ({
   pages

test-cases/general-features/src/layouts/blog.layout.js

@@ -3,7 +3,7 @@ import { html } from 'htm/preact'
 
 /**
  * @template {Record<string, any>} T
- * @typedef {import('../../../../index.js').LayoutFunction<T>} LayoutFunction
+ * @typedef {import('../../../../index.js').InternalLayoutFunction<T>} LayoutFunction
  */
 
 /**

test-cases/general-features/src/layouts/root.layout.js

@@ -3,7 +3,7 @@ import { render } from 'preact-render-to-string'
 
 /**
  * @template {Record<string, any>} T
- * @typedef {import('../../../../index.js').LayoutFunction<T>} LayoutFunction
+ * @typedef {import('../../../../index.js').InternalLayoutFunction<T>} LayoutFunction
  */
 
 /**