Remove postVars and implement global.data.{j,t}s

Author: bcomnes

.claude/settings.local.json

@@ -1,7 +1,9 @@
 {
   "permissions": {
     "allow": [
-      "Bash(node --test:*)"
+      "Bash(node --test:*)",
+      "Bash(git checkout:*)",
+      "Bash(npm test:*)"
     ]
   }
 }

README.md

@@ -1,11 +1,12 @@
 /**
  * @import { DomStackOpts as DomStackOpts, Results } from './lib/builder.js'
  * @import { FSWatcher, Stats } from 'node:fs'
- * @import { PostVarsFunction, AsyncPostVarsFunction, AsyncLayoutFunction, LayoutFunction } from './lib/build-pages/page-data.js'
+ * @import { 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'
+ * @import { GlobalDataFunction, AsyncGlobalDataFunction } from './lib/build-pages/index.js'
  * @import { BuildOptions } from 'esbuild'
 */
 import { once } from 'events'
@@ -44,17 +45,13 @@ import { DomStackAggregateError } from './lib/helpers/dom-stack-aggregate-error.
  */
 
 /**
- * @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>} [T=Record<string, any>] - The shape of the derived vars object returned.
+ * @typedef {GlobalDataFunction<T>} GlobalDataFunction
  */
 
 /**
- * @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>} [T=Record<string, any>] - The shape of the derived vars object returned.
+ * @typedef {AsyncGlobalDataFunction<T>} AsyncGlobalDataFunction
  */
 
 /**
@@ -225,7 +222,7 @@ export class DomStack {
         // Combine your existing 'anymatch' function with the new extension check
         return (
           anymatch(filePath) ||
-          Boolean((stats?.isFile() && !/\.(js|css|html|md)$/.test(filePath)))
+          Boolean((stats?.isFile() && !/\.(js|mjs|cjs|ts|mts|cts|css|html|md)$/.test(filePath)))
         )
       },
       persistent: true,

index.js

@@ -9,7 +9,7 @@ import { join } from 'path'
 import pMap from 'p-map'
 import { cpus } from 'os'
 import { keyBy } from '../helpers/key-by.js'
-import { resolveVars } from './resolve-vars.js'
+import { resolveVars, resolveGlobalData } from './resolve-vars.js'
 import { pageBuilders, templateBuilder } from './page-builders/index.js'
 import { PageData, resolveLayout } from './page-data.js'
 import { pageWriter } from './page-builders/page-writer.js'
@@ -25,6 +25,32 @@ const __dirname = import.meta.dirname
  * }} PageBuilderReport
  */
 
+/**
+ * Parameters passed to a global.data.js default export function.
+ * @typedef {object} GlobalDataFunctionParams
+ * @property {PageData<any, any, any>[]} pages - Fully initialized PageData instances for all pages.
+ */
+
+/**
+ * Synchronous global.data function. Receives initialized PageData[] (with .vars, .pageInfo, etc.)
+ * and returns an object stamped onto every page's vars before rendering begins.
+ *
+ * @template {Record<string, any>} [T=Record<string, any>] - The shape of the derived vars object returned.
+ * @callback GlobalDataFunction
+ * @param {GlobalDataFunctionParams} params
+ * @returns {T | Promise<T>}
+ */
+
+/**
+ * Asynchronous global.data function. Receives initialized PageData[] (with .vars, .pageInfo, etc.)
+ * and returns an object stamped onto every page's vars before rendering begins.
+ *
+ * @template {Record<string, any>} [T=Record<string, any>] - The shape of the derived vars object returned.
+ * @callback AsyncGlobalDataFunction
+ * @param {GlobalDataFunctionParams} params
+ * @returns {Promise<T>}
+ */
+
 /**
  * @typedef {BuildStep<
  *          'page',
@@ -178,6 +204,20 @@ export async function buildPagesDirect (src, dest, siteData, _opts) {
     return pageData
   }, { concurrency: MAX_CONCURRENCY })
 
+  // Run global.data.js after all pages are initialized — receives fully resolved PageData[]
+  // so it can filter/sort by page.vars.layout, page.vars.publishDate, etc.
+  const globalDataVars = await resolveGlobalData({
+    globalDataPath: siteData.globalData?.filepath,
+    pages,
+  })
+
+  // Stamp globalDataVars onto each page so they appear in page.vars at render time.
+  if (Object.keys(globalDataVars).length > 0) {
+    for (const page of pages) {
+      page.globalDataVars = globalDataVars
+    }
+  }
+
   if (result.errors.length > 0) return result
 
   /** @type {[number, number]} Divided concurrency valus */

lib/build-pages/index.js

@@ -76,52 +76,6 @@ export async function resolveLayout (layoutPath) {
   * @typedef {LayoutFunction<T, U, V> | AsyncLayoutFunction<T, U, V>} InternalLayoutFunction
   */
 
-/**
-  * 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 {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
@@ -132,14 +86,13 @@ export class PageData {
   /** @type {PageInfo} */ pageInfo
   /** @type {ResolvedLayout<T, U, V> | null | undefined} */ layout
   /** @type {object} */ globalVars
+  /** @type {object} */ globalDataVars = {}
   /** @type {object?} */ pageVars = null
-  /** @type {function?} */ postVars = null
   /** @type {object?} */ builderVars = null
   /** @type {string[]} */ styles = []
   /** @type {string[]} */ scripts = []
   /** @type {WorkerFiles} */ workerFiles = {}
   /** @type {boolean} */ #initialized = false
-  /** @type {T?} */ #renderedPostVars = null
   /** @type {string?} */ #defaultStyle = null
   /** @type {string?} */ #defaultClient = null
   /** @type {BuilderOptions} */ builderOptions
@@ -185,10 +138,11 @@ export class PageData {
    */
   get vars () {
     if (!this.#initialized) throw new Error('Initialize PageData before accessing vars')
-    const { globalVars, pageVars, builderVars } = this
+    const { globalVars, globalDataVars, pageVars, builderVars } = this
     // @ts-ignore
     return {
       ...globalVars,
+      ...globalDataVars,
       ...pageVars,
       ...builderVars,
     }
@@ -202,28 +156,6 @@ export class PageData {
     return this.workerFiles
   }
 
-  /**
-   * @type {AsyncPostVarsFunction<T, U, V>}
-   */
-  async #renderPostVars ({ vars, styles, scripts, pages, page, workers }) {
-    if (!this.#initialized) throw new Error('Initialize PageData before accessing renderPostVars')
-    if (!this.postVars) return this.vars
-    if (this.#renderedPostVars) return this.#renderedPostVars
-
-    const { globalVars, pageVars, builderVars } = this
-
-    const renderedPostVars = {
-      ...globalVars,
-      ...pageVars,
-      ...(await this.postVars({ vars, styles, scripts, pages, page, workers })),
-      ...builderVars,
-    }
-
-    this.#renderedPostVars = renderedPostVars
-
-    return renderedPostVars
-  }
-
   /**
    * [init description]
    * @param  {object} params - Parameters required to initialize
@@ -238,9 +170,7 @@ export class PageData {
       varsPath: pageVars?.filepath,
       resolveVars: globalVars,
     })
-    this.postVars = await resolvePostVars({
-      varsPath: pageVars?.filepath,
-    })
+    await resolvePostVars({ varsPath: pageVars?.filepath }) // throws if postVars export is detected
 
     const builder = pageBuilders[type]
     const { vars: builderVars } = await builder({ pageInfo, options: this.builderOptions })
@@ -303,9 +233,8 @@ export class PageData {
     if (!pageInfo) throw new Error('A page is required to render')
     const builder = pageBuilders[pageInfo.type]
     const { pageLayout } = await builder({ pageInfo, options: builderOptions })
-    const renderedPostVars = await this.#renderPostVars({ vars, styles, scripts, pages, page: pageInfo, workers })
     // @ts-expect-error - Builder types vary by page type, but the runtime type is correct
-    const results = await pageLayout({ vars: renderedPostVars, styles, scripts, pages, page: pageInfo, workers })
+    const results = await pageLayout({ vars, styles, scripts, pages, page: pageInfo, workers })
     return results
   }
 
@@ -316,15 +245,14 @@ export class PageData {
    */
   async renderFullPage ({ pages }) {
     if (!this.#initialized) throw new Error('Must be initialized before rendering full pages')
-    const { pageInfo, layout, vars, styles, scripts, workers } = this
+    const { pageInfo, layout, vars, styles, scripts } = this
     if (!pageInfo) throw new Error('A page is required to render')
     if (!layout) throw new Error('A layout is required to render')
-    const renderedPostVars = await this.#renderPostVars({ vars, styles, scripts, pages, page: pageInfo, workers })
     const innerPage = await this.renderInnerPage({ pages })
 
     return pretty(
       await layout.render({
-        vars: renderedPostVars,
+        vars,
         styles,
         scripts,
         page: pageInfo,

lib/build-pages/page-data.js

@@ -5,7 +5,7 @@
  * @param {string} [params.varsPath] - Path to the file containing the variables.
  * @param {object} [params.resolveVars] - Any variables you want passed to the reolveFunction.
  * @param {string} [params.key='default'] - The key to extract from the imported module. Default: 'default'
- * @returns {Promise<object|function>} - Returns the resolved variables. If the imported variable is a function, it executes and returns its result. Otherwise, it returns the variable directly.
+ * @returns {Promise<object>} - Returns the resolved variables. If the imported variable is a function, it executes and returns its result. Otherwise, it returns the variable directly.
  */
 export async function resolveVars ({
   varsPath,
@@ -31,12 +31,44 @@ export async function resolveVars ({
   }
 }
 
+/**
+ * @import { PageData } from './page-data.js'
+ */
+
+/**
+ * Resolve and call a global.data.js file with the initialized PageData array.
+ * Receives fully resolved PageData instances (with .vars, .pageInfo, etc.) so
+ * that global.data.js can filter and aggregate by layout, publishDate, title, etc.
+ * Returns an empty object if no file is provided or the file exports nothing useful.
+ *
+ * @param {object} params
+ * @param {string} [params.globalDataPath] - Path to the global.data file.
+ * @param {PageData<any, any, any>[]} params.pages - Initialized PageData array.
+ * @returns {Promise<object>}
+ */
+export async function resolveGlobalData ({ globalDataPath, pages }) {
+  if (!globalDataPath) return {}
+
+  const imported = await import(globalDataPath)
+  const maybeGlobalData = imported.default
+
+  if (isFunction(maybeGlobalData)) {
+    const result = await maybeGlobalData({ pages })
+    if (isObject(result)) return result
+    throw new Error('global.data default export function must return an object')
+  } else if (isObject(maybeGlobalData)) {
+    return maybeGlobalData
+  } else {
+    return {}
+  }
+}
+
 /**
  * Resolve variables by importing them from a specified path.
  *
  * @param {object} params
  * @param {string} [params.varsPath] - Path to the file containing the variables.
- * @returns {Promise<function|null>} - Returns the resolved variables. If the imported variable is a function, it executes and returns its result. Otherwise, it returns the variable directly.
+ * @returns {Promise<null>}
  */
 export async function resolvePostVars ({
   varsPath,
@@ -47,14 +79,14 @@ export async function resolvePostVars ({
   const maybePostVars = imported.postVars
 
   if (maybePostVars) {
-    if (isFunction(maybePostVars)) {
-      return maybePostVars
-    } else {
-      throw new Error('postVars must export a function')
-    }
-  } else {
-    return null
+    throw new Error(
+      `postVars is no longer supported (found in ${varsPath}). ` +
+      'Move data aggregation to a global.data.js file instead. ' +
+      'See the domstack docs for details.'
+    )
   }
+
+  return null
 }
 
 /**

lib/build-pages/resolve-vars.js

@@ -11,6 +11,7 @@
  *  'DOM_STACK_WARNING_DUPLICATE_ESBUILD_SETTINGS' |
  *  'DOM_STACK_WARNING_DUPLICATE_MARKDOWN_IT_SETTINGS' |
  *  'DOM_STACK_WARNING_DUPLICATE_GLOBAL_VARS' |
+ *  'DOM_STACK_WARNING_DUPLICATE_GLOBAL_DATA' |
  *  'DOM_STACK_WARNING_PAGE_MD_SHADOWS_README'
  *  } DomStackWarningCode
  */