From 98edb506207bc6795f5c4ea9f4719b09f53ec654 Mon Sep 17 00:00:00 2001 From: Bret Comnes Date: Sat, 18 Apr 2026 10:55:12 -0700 Subject: [PATCH 1/6] export PageData, PageInfo, and param types from package entry point The package exported function types (LayoutFunction, PageFunction, etc.) but not the data types those functions receive: PageData, PageInfo, TemplateInfo, and the various Params types. Users who want full type safety for layouts, templates, global.data.js, and page functions had no first-class way to import these types. They had to either reach into internal module paths or write partial inline JSDoc. This adds PageData as a runtime re-export (useful for instanceof checks) and re-exports PageInfo, TemplateInfo, LayoutFunctionParams, GlobalDataFunctionParams, PageFunctionParams, and TemplateFunctionParams as JSDoc typedefs from the package entry point. --- index.js | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/index.js b/index.js index 3a062db..a6f6eab 100644 --- a/index.js +++ b/index.js @@ -2,12 +2,12 @@ * @import { DomStackOpts as DomStackOpts, Results, SiteData } from './lib/builder.js' * @import { Stats } from 'node:fs' * @import { FSWatcher } from 'chokidar' - * @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 { AsyncLayoutFunction, LayoutFunction, LayoutFunctionParams } from './lib/build-pages/page-data.js' + * @import { PageFunction, AsyncPageFunction, PageFunctionParams } from './lib/build-pages/page-builders/page-writer.js' + * @import { TemplateFunction, TemplateFunctionParams } 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, WorkerBuildStepResult } from './lib/build-pages/index.js' + * @import { GlobalDataFunction, AsyncGlobalDataFunction, WorkerBuildStepResult, GlobalDataFunctionParams } from './lib/build-pages/index.js' * @import { BuildOptions, BuildContext } from 'esbuild' * @import { PageInfo, TemplateInfo } from './lib/identify-pages.js' */ @@ -49,6 +49,8 @@ import { resolveVars } from './lib/build-pages/resolve-vars.js' import { ensureDest } from './lib/helpers/ensure-dest.js' import { DomStackAggregateError } from './lib/helpers/domstack-aggregate-error.js' +export { PageData } from './lib/build-pages/page-data.js' + /** * @typedef {BuildOptions} BuildOptions */ @@ -103,6 +105,36 @@ import { DomStackAggregateError } from './lib/helpers/domstack-aggregate-error.j * @typedef {TemplateOutputOverride} TemplateOutputOverride */ +/** + * @typedef {PageInfo} PageInfo + */ + +/** + * @typedef {TemplateInfo} TemplateInfo + */ + +/** + * @template {Record} T - The type of variables passed to the layout function + * @template [U=any] U - The return type of the page function + * @template [V=string] V - The return type of the layout function + * @typedef {LayoutFunctionParams} LayoutFunctionParams + */ + +/** + * @typedef {GlobalDataFunctionParams} GlobalDataFunctionParams + */ + +/** + * @template {Record} T - The type of variables passed to the page function + * @template [U=any] U - The return type of the page function + * @typedef {PageFunctionParams} PageFunctionParams + */ + +/** + * @template {Record} T - The type of variables for the template function + * @typedef {TemplateFunctionParams} TemplateFunctionParams + */ + const DEFAULT_IGNORES = /** @type {const} */ ([ '.*', 'coverage', From 02c04ba4d2f213e2819428c90203c5c77e0be56c Mon Sep 17 00:00:00 2001 From: Bret Comnes Date: Sat, 18 Apr 2026 12:16:56 -0700 Subject: [PATCH 2/6] fix: remove TemplateFunctionParams from public API TemplateFunctionParams was a tuple type (Parameters>), inconsistent with the object-shaped LayoutFunctionParams and PageFunctionParams. Remove it from the public index.js exports and inline the tuple usage directly in the TemplateAsyncIterator internal definition. Co-Authored-By: Claude Sonnet 4.6 --- index.js | 6 +----- lib/build-pages/page-builders/template-builder.js | 7 +------ 2 files changed, 2 insertions(+), 11 deletions(-) diff --git a/index.js b/index.js index a6f6eab..47e54e2 100644 --- a/index.js +++ b/index.js @@ -4,7 +4,7 @@ * @import { FSWatcher } from 'chokidar' * @import { AsyncLayoutFunction, LayoutFunction, LayoutFunctionParams } from './lib/build-pages/page-data.js' * @import { PageFunction, AsyncPageFunction, PageFunctionParams } from './lib/build-pages/page-builders/page-writer.js' - * @import { TemplateFunction, TemplateFunctionParams } from './lib/build-pages/page-builders/template-builder.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, WorkerBuildStepResult, GlobalDataFunctionParams } from './lib/build-pages/index.js' @@ -130,10 +130,6 @@ export { PageData } from './lib/build-pages/page-data.js' * @typedef {PageFunctionParams} PageFunctionParams */ -/** - * @template {Record} T - The type of variables for the template function - * @typedef {TemplateFunctionParams} TemplateFunctionParams - */ const DEFAULT_IGNORES = /** @type {const} */ ([ '.*', diff --git a/lib/build-pages/page-builders/template-builder.js b/lib/build-pages/page-builders/template-builder.js index cdd4bf4..3f64f58 100644 --- a/lib/build-pages/page-builders/template-builder.js +++ b/lib/build-pages/page-builders/template-builder.js @@ -24,16 +24,11 @@ import { writeFile, mkdir } from 'fs/promises' * } - The results of a template build */ -/** - * @template {Record} T - The type of variables for the template function parameters - * @typedef {Parameters>} TemplateFunctionParams -*/ - /** * Callback for rendering a template with an async iterator. * @template T - The type of variables for the template async iterator * @callback TemplateAsyncIterator - * @param {TemplateFunctionParams[0]} params - Parameters of the template function. + * @param {Parameters>[0]} params - Parameters of the template function. * @returns {AsyncIterable} */ From 00a5d63e85fdf9a7b3823673fd8a2be2fbd7d374 Mon Sep 17 00:00:00 2001 From: Bret Comnes Date: Sat, 18 Apr 2026 12:52:49 -0700 Subject: [PATCH 3/6] Add TemplateFunctionParams as an object-shaped typedef --- index.js | 5 +++++ lib/build-pages/page-builders/template-builder.js | 10 ++++++++++ 2 files changed, 15 insertions(+) diff --git a/index.js b/index.js index 47e54e2..aa9d6f4 100644 --- a/index.js +++ b/index.js @@ -7,6 +7,7 @@ * @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 { TemplateFunctionParams } from './lib/build-pages/page-builders/template-builder.js' * @import { GlobalDataFunction, AsyncGlobalDataFunction, WorkerBuildStepResult, GlobalDataFunctionParams } from './lib/build-pages/index.js' * @import { BuildOptions, BuildContext } from 'esbuild' * @import { PageInfo, TemplateInfo } from './lib/identify-pages.js' @@ -130,6 +131,10 @@ export { PageData } from './lib/build-pages/page-data.js' * @typedef {PageFunctionParams} PageFunctionParams */ +/** + * @template {Record} [T=Record] - The type of variables for the template function + * @typedef {TemplateFunctionParams} TemplateFunctionParams + */ const DEFAULT_IGNORES = /** @type {const} */ ([ '.*', diff --git a/lib/build-pages/page-builders/template-builder.js b/lib/build-pages/page-builders/template-builder.js index 3f64f58..1b405cc 100644 --- a/lib/build-pages/page-builders/template-builder.js +++ b/lib/build-pages/page-builders/template-builder.js @@ -11,6 +11,16 @@ import { writeFile, mkdir } from 'fs/promises' * content: string * }} TemplateOutputOverride */ +/** + * The parameters object passed to a {@link TemplateFunction} or {@link TemplateAsyncIterator}. + * + * @template {Record} [T=Record] - The type of variables for the template + * @typedef {object} TemplateFunctionParams + * @property {T} vars - All of the site globalVars. + * @property {TemplateInfo} template - Info about the current template. + * @property {PageData[]} pages - An array of info about every page. + */ + /** * Callback for rendering a template. * From cd7d964364c2781c3739f6fc1e188d12020c43c4 Mon Sep 17 00:00:00 2001 From: Bret Comnes Date: Sat, 18 Apr 2026 14:45:48 -0700 Subject: [PATCH 4/6] Add type smoke test for public entry point exports Imports PageData at runtime and verifies it is a class. TypeScript also checks the @typedef imports for PageInfo, TemplateInfo, LayoutFunctionParams, GlobalDataFunctionParams, PageFunctionParams, and TemplateFunctionParams at compile time via npm run test:tsc. Co-Authored-By: Claude Sonnet 4.6 --- test-cases/type-exports/index.test.js | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 test-cases/type-exports/index.test.js diff --git a/test-cases/type-exports/index.test.js b/test-cases/type-exports/index.test.js new file mode 100644 index 0000000..b7c781b --- /dev/null +++ b/test-cases/type-exports/index.test.js @@ -0,0 +1,20 @@ +// @ts-check +import { test } from 'node:test' +import assert from 'node:assert' +import { PageData } from '../../index.js' + +/** + * Smoke test that all public types are importable from the package entry point. + * The @typedef imports below are verified by TypeScript at compile time via `npm run test:tsc`. + * + * @typedef {import('../../index.js').PageInfo} PageInfo + * @typedef {import('../../index.js').TemplateInfo} TemplateInfo + * @typedef {import('../../index.js').LayoutFunctionParams} LayoutFunctionParams + * @typedef {import('../../index.js').GlobalDataFunctionParams} GlobalDataFunctionParams + * @typedef {import('../../index.js').PageFunctionParams} PageFunctionParams + * @typedef {import('../../index.js').TemplateFunctionParams} TemplateFunctionParams + */ + +test('PageData is importable from the package entry point', () => { + assert.strictEqual(typeof PageData, 'function', 'PageData is a class') +}) From a25c41353e6612a879c0a6fc5232d962286d99f0 Mon Sep 17 00:00:00 2001 From: Bret Comnes Date: Sat, 18 Apr 2026 19:49:35 -0700 Subject: [PATCH 5/6] Use TemplateFunctionParams in TemplateAsyncIterator instead of Parameters<>[0] Co-Authored-By: Claude Sonnet 4.6 --- lib/build-pages/page-builders/template-builder.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/build-pages/page-builders/template-builder.js b/lib/build-pages/page-builders/template-builder.js index 1b405cc..d055aa8 100644 --- a/lib/build-pages/page-builders/template-builder.js +++ b/lib/build-pages/page-builders/template-builder.js @@ -38,7 +38,7 @@ import { writeFile, mkdir } from 'fs/promises' * Callback for rendering a template with an async iterator. * @template T - The type of variables for the template async iterator * @callback TemplateAsyncIterator - * @param {Parameters>[0]} params - Parameters of the template function. + * @param {TemplateFunctionParams} params - Parameters of the template function. * @returns {AsyncIterable} */ From 51484120ad3f950a9fcc7786fc326d98353fe90f Mon Sep 17 00:00:00 2001 From: Bret Comnes Date: Sat, 18 Apr 2026 19:58:00 -0700 Subject: [PATCH 6/6] fix: add type args and fix @typedef in description to pass tsc Co-Authored-By: Claude Sonnet 4.6 --- test-cases/type-exports/index.test.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/test-cases/type-exports/index.test.js b/test-cases/type-exports/index.test.js index b7c781b..ac0ab5d 100644 --- a/test-cases/type-exports/index.test.js +++ b/test-cases/type-exports/index.test.js @@ -5,13 +5,13 @@ import { PageData } from '../../index.js' /** * Smoke test that all public types are importable from the package entry point. - * The @typedef imports below are verified by TypeScript at compile time via `npm run test:tsc`. + * The type imports below are verified by TypeScript at compile time via `npm run test:tsc`. * * @typedef {import('../../index.js').PageInfo} PageInfo * @typedef {import('../../index.js').TemplateInfo} TemplateInfo - * @typedef {import('../../index.js').LayoutFunctionParams} LayoutFunctionParams + * @typedef {import('../../index.js').LayoutFunctionParams} LayoutFunctionParams * @typedef {import('../../index.js').GlobalDataFunctionParams} GlobalDataFunctionParams - * @typedef {import('../../index.js').PageFunctionParams} PageFunctionParams + * @typedef {import('../../index.js').PageFunctionParams} PageFunctionParams * @typedef {import('../../index.js').TemplateFunctionParams} TemplateFunctionParams */