diff --git a/README.md b/README.md index 47a5704..c5c1e49 100644 --- a/README.md +++ b/README.md @@ -397,7 +397,7 @@ The default `root.layout.js` is featured below, and is implemented with [`uhtml` import { html, render } from 'uhtml-isomorphic' /** - * @template T extends object + * @template {Record} T * @typedef {import('top-bun').LayoutFunction} LayoutFunction */ @@ -460,7 +460,7 @@ import defaultRootLayout from './root.layout.js' import { html } from 'uhtml-isomorphic' /** - * @template T extends object + * @template {Record} T * @typedef {import('top-bun').LayoutFunction} LayoutFunction */ diff --git a/examples/css-modules/src/layouts/root.layout.js b/examples/css-modules/src/layouts/root.layout.js index 66f4e42..7b1e3d7 100644 --- a/examples/css-modules/src/layouts/root.layout.js +++ b/examples/css-modules/src/layouts/root.layout.js @@ -3,7 +3,7 @@ import { html } from 'htm/preact' import { render } from 'preact-render-to-string' /** - * @template T extends object + * @template {Record} T * @typedef {import('../build-pages/resolve-layout.js').LayoutFunction} LayoutFunction */ diff --git a/examples/preact/src/layouts/root.layout.js b/examples/preact/src/layouts/root.layout.js index 66f4e42..7b1e3d7 100644 --- a/examples/preact/src/layouts/root.layout.js +++ b/examples/preact/src/layouts/root.layout.js @@ -3,7 +3,7 @@ import { html } from 'htm/preact' import { render } from 'preact-render-to-string' /** - * @template T extends object + * @template {Record} T * @typedef {import('../build-pages/resolve-layout.js').LayoutFunction} LayoutFunction */ diff --git a/examples/tailwind/src/layouts/root.layout.js b/examples/tailwind/src/layouts/root.layout.js index c4b338c..3a6b6dc 100644 --- a/examples/tailwind/src/layouts/root.layout.js +++ b/examples/tailwind/src/layouts/root.layout.js @@ -3,7 +3,7 @@ import { html } from 'htm/preact' import { render } from 'preact-render-to-string' /** - * @template T extends object + * @template {Record} T * @typedef {import('../build-pages/resolve-layout.js').LayoutFunction} LayoutFunction */ diff --git a/index.js b/index.js index 65546c8..a21fb54 100644 --- a/index.js +++ b/index.js @@ -20,27 +20,27 @@ import { TopBunAggregateError } from './lib/helpers/top-bun-aggregate-error.js' */ /** - * @template T extends Object. + * @template {Record} T * @typedef {import('./lib/build-pages/resolve-layout.js').LayoutFunction} LayoutFunction */ /** - * @template T extends Object. + * @template {Record} T * @typedef {import('./lib/build-pages/resolve-vars.js').PostVarsFunction} PostVarsFunction */ /** - * @template T extends Object. + * @template {Record} T * @typedef {import('./lib/build-pages/page-builders/page-writer.js').PageFunction} PageFunction */ /** - * @template T extends Object. + * @template {Record} T * @typedef {import('./lib/build-pages/page-builders/template-builder.js').TemplateFunction} TemplateFunction */ /** - * @template T extends Object. + * @template {Record} T * @typedef {import('./lib/build-pages/page-builders/template-builder.js').TemplateAsyncIterator} TemplateAsyncIterator */ @@ -48,10 +48,23 @@ import { TopBunAggregateError } from './lib/helpers/top-bun-aggregate-error.js' * @typedef {import('./lib/build-pages/page-builders/template-builder.js').TemplateOutputOverride} TemplateOutputOverride */ +const DEFAULT_IGNORES = /** @type {const} */ ([ + '.*', + 'coverage', + 'node_modules', + 'package.json', + 'package-lock.json', + 'pnpm-lock.yaml', + 'yarn.lock', +]) + +/** + * @template {TopBunOpts} [CurrentOpts=TopBunOpts] + */ export class TopBun { /** @type {string} */ #src = '' /** @type {string} */ #dest = '' - /** @type {TopBunOpts} */ opts = {} + /** @type {Readonly} */ opts /** @type {FSWatcher?} */ #watcher = null /** @type {any?} */ #cpxWatcher = null /** @type {browserSync.BrowserSyncInstance?} */ #browserSyncServer = null @@ -60,20 +73,24 @@ export class TopBun { * * @param {string} src - The src path of the page build * @param {string} dest - The dest path of the page build - * @param {TopBunOpts} [opts] - The options for the site build + * @param {CurrentOpts} [opts] - The options for the site build */ - constructor (src, dest, opts = {}) { - assert(src, 'src is a required argument') - assert(dest, 'dest is a required argument') - - const defaultIgnore = ['.*', 'node_modules', basename(dest), 'package.json', 'pacakge-lock.json'] - - opts.ignore = defaultIgnore.concat(makeArray(opts.ignore)) + constructor (src, dest, opts = /** @type {CurrentOpts} */ ({})) { + if (!src || typeof src !== 'string') throw new TypeError('src should be a (non-empty) string') + if (!dest || typeof dest !== 'string') throw new TypeError('dest should be a (non-empty) string') + if (!opts || typeof opts !== 'object') throw new TypeError('opts should be an object') this.#src = src this.#dest = dest - this.opts = opts + this.opts = { + ...opts, + ignore: [ + ...DEFAULT_IGNORES, + basename(dest), + ...makeArray(opts.ignore), + ], + } } get watching () { diff --git a/lib/build-pages/page-builders/html/index.js b/lib/build-pages/page-builders/html/index.js index 561f07c..dc20a72 100644 --- a/lib/build-pages/page-builders/html/index.js +++ b/lib/build-pages/page-builders/html/index.js @@ -2,15 +2,10 @@ import assert from 'node:assert' import { readFile } from 'fs/promises' import Handlebars from 'handlebars' -/** - * @template T - * @typedef {import('../page-writer.js').PageBuilderType} PageBuilderType - */ - /** * Build all of the bundles using esbuild. - * @template T - * @type {PageBuilderType} + * @template {Record} T + * @type {import('../page-writer.js').PageBuilderType} */ export async function htmlBuilder ({ pageInfo }) { assert(pageInfo.type === 'html', 'html builder requires a "html" page type') diff --git a/lib/build-pages/page-builders/js/index.js b/lib/build-pages/page-builders/js/index.js index e4df2ab..fc192da 100644 --- a/lib/build-pages/page-builders/js/index.js +++ b/lib/build-pages/page-builders/js/index.js @@ -1,14 +1,9 @@ import assert from 'node:assert' -/** - * @template T - * @typedef {import('../page-writer.js').PageBuilderType} PageBuilderType - */ - /** * Build all of the bundles using esbuild. - * @template T - * @type {PageBuilderType} + * @template {Record} T + * @type {import('../page-writer.js').PageBuilderType} */ export async function jsBuilder ({ pageInfo }) { assert(pageInfo.type === 'js', 'js page builder requries "js" page type') diff --git a/lib/build-pages/page-builders/md/index.js b/lib/build-pages/page-builders/md/index.js index 6c797de..192ea4d 100644 --- a/lib/build-pages/page-builders/md/index.js +++ b/lib/build-pages/page-builders/md/index.js @@ -7,15 +7,10 @@ import { getMd, renderMd } from './get-md.js' const md = getMd() -/** - * @template T - * @typedef {import('../page-writer.js').PageBuilderType} PageBuilderType - */ - /** * Build all of the bundles using esbuild. - * @template T - * @type {PageBuilderType} + * @template {Record} T + * @type {import('../page-writer.js').PageBuilderType} */ export async function mdBuilder ({ pageInfo }) { assert(pageInfo.type === 'md', 'md builder requires an "md" page type') diff --git a/lib/build-pages/page-builders/page-writer.js b/lib/build-pages/page-builders/page-writer.js index 7f20223..35c29be 100644 --- a/lib/build-pages/page-builders/page-writer.js +++ b/lib/build-pages/page-builders/page-writer.js @@ -6,7 +6,7 @@ import { writeFile, mkdir } from 'fs/promises' */ /** - * @template T extends Object. + * @template {Record} T * @typedef {import('../page-data.js').PageData} PageData */ @@ -14,7 +14,7 @@ import { writeFile, mkdir } from 'fs/promises' * pageLayout functions Can be used to type a name.layout.js file * * @async - * @template T extends Object. + * @template {Record} T * @callback PageFunction * @param {object} params - The parameters for the pageLayout. * @param {T} params.vars - All default, global, layout, page, and builder vars shallow merged. @@ -26,14 +26,14 @@ import { writeFile, mkdir } from 'fs/promises' */ /** - * @template T extends Object. + * @template {Record} T * @typedef PageBuilderResult * @property {object} vars - Any variables resolved by the builder * @property {PageFunction} pageLayout - The function that returns the rendered page */ /** - * @template T extends Object. + * @template {Record} T * @callback PageBuilderType * * @param {object} params @@ -43,7 +43,7 @@ import { writeFile, mkdir } from 'fs/promises' /** * Handles rendering and writing a page to disk - * @template T extends object + * @template {Record} T * @param {object} params * @param {string} params.src - The src folder. * @param {string} params.dest - The dest folder. diff --git a/lib/build-pages/page-builders/template-builder.js b/lib/build-pages/page-builders/template-builder.js index 00416d1..0ad20bc 100644 --- a/lib/build-pages/page-builders/template-builder.js +++ b/lib/build-pages/page-builders/template-builder.js @@ -6,7 +6,7 @@ import { writeFile, mkdir } from 'fs/promises' */ /** - * @template T extends object + * @template {Record} T * @typedef {import('../page-data.js').PageData} PageData */ @@ -18,7 +18,7 @@ import { writeFile, mkdir } from 'fs/promises' /** * Callback for rendering a template. * - * @template T extends Object., + * @template {Record} T * @callback TemplateFunction * @param {object} params - The parameters for the template. * @param {T} params.vars - All of the site globalVars. @@ -29,7 +29,7 @@ import { writeFile, mkdir } from 'fs/promises' */ /** - * @template T + * @template {Record} T * @typedef {Parameters>} TemplateFunctionParams */ @@ -51,7 +51,7 @@ import { writeFile, mkdir } from 'fs/promises' /** * The template builder renders templates agains the globalVars variables - * @template T extends Object. + * @template {Record} T * @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. diff --git a/lib/build-pages/page-data.js b/lib/build-pages/page-data.js index cfaeced..fcd371f 100644 --- a/lib/build-pages/page-data.js +++ b/lib/build-pages/page-data.js @@ -13,14 +13,9 @@ import pretty from 'pretty' * @typedef {import('./index.js').ResolvedLayout} ResolvedLayout */ -/** - * @template T - * @typedef {import('./resolve-vars.js').PostVarsFunction} PostVarsFunction - */ - /** * Represents the data for a page. - * @template T extends object + * @template {Record} T */ export class PageData { /** @type {PageInfo} */ pageInfo @@ -84,7 +79,7 @@ export class PageData { } /** - * @type {PostVarsFunction} + * @type {import('./resolve-vars.js').PostVarsFunction} */ async #renderPostVars ({ vars, styles, scripts, pages, page }) { if (!this.#initalized) throw new Error('Initialize PageData before accessing renderPostVars') diff --git a/lib/build-pages/resolve-layout.js b/lib/build-pages/resolve-layout.js index a1d120b..2d96ffc 100644 --- a/lib/build-pages/resolve-layout.js +++ b/lib/build-pages/resolve-layout.js @@ -3,7 +3,7 @@ */ /** - * @template T extends object + * @template {Record} T * @typedef {import('./page-data.js').PageData} PageData */ diff --git a/lib/build-pages/resolve-vars.js b/lib/build-pages/resolve-vars.js index 46d53d0..3e181cc 100644 --- a/lib/build-pages/resolve-vars.js +++ b/lib/build-pages/resolve-vars.js @@ -1,12 +1,3 @@ -/** - * @typedef {import('../identify-pages.js').PageInfo} PageInfo - */ - -/** - * @template T - * @typedef {import('./page-data.js').PageData} PageData - */ - /** * Resolve variables by importing them from a specified path. * @@ -44,14 +35,14 @@ export async function resolveVars ({ * postVars functions Can be used to generate page vars but access all page data * * @async - * @template T extends Object. + * @template {Record} T * @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[]} params.pages - An array of info about every page + * @param {import('../identify-pages.js').PageInfo} params.page - Info about the current page + * @param {import('./page-data.js').PageData[]} params.pages - An array of info about every page * @returns {Promise} The rendered postVars */ diff --git a/lib/builder.js b/lib/builder.js index 916ec8c..9c2253b 100644 --- a/lib/builder.js +++ b/lib/builder.js @@ -40,12 +40,12 @@ import { ensureDest } from './helpers/ensure-dest.js' /** * @typedef TopBunOpts - * @property {string[]?} [ignore] - Array of file/folder patterns to ignore. - * @property {boolean?} [static=true] - Enable/disable static file processing - * @property {boolean?} [metafile=true] - Enable/disable the writing of the esbuild metadata file. - * @property {string[]?} [ignore=[]] - Array of ignore strings - * @property {string[]?} [target=[]] - Array of target strings to pass to esbuild - * @property {boolean?} [buildDrafts=false] - Build draft files with the published:false variable + * @property {string[]|undefined} [ignore] - Array of file/folder patterns to ignore. + * @property {boolean|undefined} [static=true] - Enable/disable static file processing + * @property {boolean|undefined} [metafile=true] - Enable/disable the writing of the esbuild metadata file. + * @property {string[]|undefined} [ignore=[]] - Array of ignore strings + * @property {string[]|undefined} [target=[]] - Array of target strings to pass to esbuild + * @property {boolean|undefined} [buildDrafts=false] - Build draft files with the published:false variable */ /** diff --git a/lib/defaults/default.root.layout.js b/lib/defaults/default.root.layout.js index bc4dee0..a14f0ef 100644 --- a/lib/defaults/default.root.layout.js +++ b/lib/defaults/default.root.layout.js @@ -2,7 +2,7 @@ import { html, render } from 'uhtml-isomorphic' /** - * @template T extends object + * @template {Record} T * @typedef {import('../build-pages/resolve-layout.js').LayoutFunction} LayoutFunction */ diff --git a/test-cases/general-features/src/blog/page.js b/test-cases/general-features/src/blog/page.js index 6edb825..543804a 100644 --- a/test-cases/general-features/src/blog/page.js +++ b/test-cases/general-features/src/blog/page.js @@ -3,12 +3,7 @@ import { html } from 'uhtml-isomorphic' import { dirname, basename } from 'node:path' /** - * @template T - * @typedef {import('../../../../index.js').LayoutFunction} LayoutFunction - */ - -/** - * @type {LayoutFunction<{}>} + * @type {import('../../../../index.js').LayoutFunction<{}>} */ export default async function blogIndex ({ /** vars */ diff --git a/test-cases/general-features/src/feeds.template.js b/test-cases/general-features/src/feeds.template.js index f57283f..5cb350b 100644 --- a/test-cases/general-features/src/feeds.template.js +++ b/test-cases/general-features/src/feeds.template.js @@ -3,22 +3,18 @@ import pMap from 'p-map' import jsonfeedToAtom from 'jsonfeed-to-atom' /** - * @template T - * @typedef {import('../../../index.js').TemplateAsyncIterator} TemplateAsyncIterator + * @type {import('../../../index.js').TemplateAsyncIterator<{ + * title: string, + * layout: string, + * siteName: string, + * homePageUrl: string, + * authorName: string, + * authorUrl: string, + * authorImgUrl: string, + * publishDate: string, + * siteDescription: string + * }>} */ - -/** @type {TemplateAsyncIterator<{ - * title: string, - * layout: string, - * siteName: string, - * homePageUrl: string, - * authorName: string, - * authorUrl: string, - * authorImgUrl: string, - * publishDate: string, - * siteDescription: string - * }>} -*/ export default async function * feedsTemplate ({ vars: { siteName, diff --git a/test-cases/general-features/src/layouts/blog.layout.js b/test-cases/general-features/src/layouts/blog.layout.js index c16da47..8128d64 100644 --- a/test-cases/general-features/src/layouts/blog.layout.js +++ b/test-cases/general-features/src/layouts/blog.layout.js @@ -3,7 +3,7 @@ import defaultRootLayout from './root.layout.js' import { html } from 'uhtml-isomorphic' /** - * @template T extends object + * @template {Record} T * @typedef {import('../../../../index.js').LayoutFunction} LayoutFunction */ diff --git a/test-cases/general-features/src/layouts/root.layout.js b/test-cases/general-features/src/layouts/root.layout.js index 2a4611a..978a634 100644 --- a/test-cases/general-features/src/layouts/root.layout.js +++ b/test-cases/general-features/src/layouts/root.layout.js @@ -2,7 +2,7 @@ import { html, render } from 'uhtml-isomorphic' /** - * @template T extends object + * @template {Record} T * @typedef {import('../../../../index.js').LayoutFunction} LayoutFunction */ diff --git a/test-cases/general-features/src/page.vars.js b/test-cases/general-features/src/page.vars.js index 6b66709..8343139 100644 --- a/test-cases/general-features/src/page.vars.js +++ b/test-cases/general-features/src/page.vars.js @@ -2,7 +2,7 @@ import { html, render } from 'uhtml-isomorphic' /** - * @template T extends Object. + * @template {Record} T * @typedef {import('../../../index.js').PostVarsFunction} PostVarsFunction */ diff --git a/test-cases/general-features/src/templates/async-iterator.template.js b/test-cases/general-features/src/templates/async-iterator.template.js index 6bdfbb1..156053d 100644 --- a/test-cases/general-features/src/templates/async-iterator.template.js +++ b/test-cases/general-features/src/templates/async-iterator.template.js @@ -1,12 +1,9 @@ /** - * @template T - * @typedef {import('../../../../index.js').TemplateAsyncIterator} TemplateAsyncIterator - */ - -/** @type {TemplateAsyncIterator<{ + * @type {import('../../../../index.js').TemplateAsyncIterator<{ * foo: string, * testVar: string - * }>} */ + * }>} + */ export default async function * ({ vars: { foo, diff --git a/test-cases/general-features/src/templates/object-array.template.js b/test-cases/general-features/src/templates/object-array.template.js index 31f920c..d55e884 100644 --- a/test-cases/general-features/src/templates/object-array.template.js +++ b/test-cases/general-features/src/templates/object-array.template.js @@ -1,10 +1,5 @@ /** - * @template T - * @typedef {import('../../../../index.js').TemplateFunction} TemplateFunction - */ - -/** - * @type {TemplateFunction<{ + * @type {import('../../../../index.js').TemplateFunction<{ * foo: string, * testVar: string * }>} diff --git a/test-cases/general-features/src/templates/simple.txt.template.js b/test-cases/general-features/src/templates/simple.txt.template.js index 24d1479..23a6032 100644 --- a/test-cases/general-features/src/templates/simple.txt.template.js +++ b/test-cases/general-features/src/templates/simple.txt.template.js @@ -1,10 +1,5 @@ /** - * @template T - * @typedef {import('../../../../index.js').TemplateFunction} TemplateFunction - */ - -/** - * @type {TemplateFunction<{ + * @type {import('../../../../index.js').TemplateFunction<{ * foo: string, * testVar: string * }>} diff --git a/test-cases/general-features/src/templates/single-object.template.js b/test-cases/general-features/src/templates/single-object.template.js index f3ea278..0a10027 100644 --- a/test-cases/general-features/src/templates/single-object.template.js +++ b/test-cases/general-features/src/templates/single-object.template.js @@ -1,10 +1,5 @@ /** - * @template T - * @typedef {import('../../../../index.js').TemplateFunction} TemplateFunction - */ - -/** - * @type {TemplateFunction<{ + * @type {import('../../../../index.js').TemplateFunction<{ * foo: string, * }>} */