From 980d33c48ea0ff6a60c98f0a879dea71b2027797 Mon Sep 17 00:00:00 2001 From: Miel Truyen Date: Sat, 25 Nov 2023 20:23:13 +0100 Subject: [PATCH] chore: documentation --- src/index.ts | 43 ++++++++++++++++++++---- src/loader.ts | 6 ++++ test/multi-entry/snapshots/test.js.snap | Bin 1703 -> 1757 bytes test/templating/snapshots/test.js.snap | Bin 783 -> 792 bytes 4 files changed, 43 insertions(+), 6 deletions(-) diff --git a/src/index.ts b/src/index.ts index 3a3ac8f..0147fbb 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,4 +1,4 @@ -import path, { extname } from "node:path"; + import type { Plugin, @@ -19,17 +19,21 @@ import type { LoadReference, BodyReference, AttributeReference, LoadFunction } from '../types/index.d.ts'; +// createFilter function is a utility that constructs a filter function from include/exclude patterns. import {createFilter} from '@rollup/pluginutils'; +// parse5 package is used for parsing HTML. import {parse as parseHtml, serialize as serializeHtml, DefaultTreeAdapterMap} from "parse5"; -import {readFile} from "node:fs/promises" +// nodejs imports (io, path) +import path, { extname, dirname } from "node:path"; +import {readFile} from "node:fs/promises" +import posix from "node:path/posix"; +import crypto from "node:crypto"; + +// utilities import {makeLoader, makeInlineId} from "./loader.js"; import {HtmlImport, HtmlModule} from "./html-module.js"; -import {dirname} from "node:path"; -import posix from "node:path/posix"; - -import crypto from "node:crypto"; const defaults: RollupHtmlOptions = { transform: (source: string)=>source,// NO-OP @@ -44,6 +48,12 @@ const defaults: RollupHtmlOptions = { const modulePrefix = `// `; const moduleSuffix = `// `; +/** + * Creates a Rollup plugin that transforms HTML files. + * + * @param {RollupHtmlOptions} opts - The options for the plugin. + * @returns {Plugin} - The Rollup plugin. + */ export default function html(opts: RollupHtmlOptions = {}): Plugin { const { publicPath, @@ -70,14 +80,35 @@ export default function html(opts: RollupHtmlOptions = {}): Plugin { let entryNames = new Map(); const pluginName = 'html2'; + /** + * Short summary: + * Intercepts the loading of the html files and parses it with parse5. + * The parsed result is iterated to check for external references that need to be including in the rollup build (via for example @rollup/plugin-url). + * To satisfy rollup a JS version of the html file is returned, optionally including a few imports left for rollup to resolve + * When the result is generated the rollup result for the html file and any of its inlined assets are stripped from the output. + * and replaced with the html file. + * + * Caveats: + * - to get the resulting html content file we're parsing the evaluating the result JS module and take its default export + * [warn] other plugins such as CJS transformer and hot-reload can severely screw this up. + * - sourcemaps won't work yet (to add support we'd need to rewrite using magic-string?) + * - to fix the naming of resulting html files, and behave properly when files are entryPoints or not... we're fighting rollup alot + * + * + * Rework by testing a stripped down version with JS imports? + * - the logic in load should be moved to a transform, properly use rollups ability to specify the plugin should run 'pre' other hooks and see if that allows us to intercept before a commonjs or some other tool horribly transpiles our code + * - we might need to know which output is being used to properly extract the html back from the result? (in case of not being included in a JS file) + */ return { name: pluginName,// TODO: Need a better name, original plugin was just named `html` and might still make sense to use in conjunction with this one + // Track html entrypoints buildStart(options){ entryNames = new Map(Object.entries(typeof(options.input)==='object'?options.input:{[options.input]:[options.input]}) .map(([k,v])=>[v,k]) ); }, + resolveId: { async handler(specifier: string, importer: string | undefined, diff --git a/src/loader.ts b/src/loader.ts index 5075b61..f5a5ec6 100644 --- a/src/loader.ts +++ b/src/loader.ts @@ -46,6 +46,12 @@ export function makeInlineId(sourceId: string, node: DefaultTreeAdapterMap['chil return [sourceId, [makeHtmlPath(node), 'js'].join('.')].join('.'); } +/** + * Creates a loader function that maps node types and attributes to load operations. + * + * @param mappings - An array of NodeMapping objects specifying how to map and load different nodes. + * @returns A LoadNodeCallback function that can be used to load nodes based on the mappings. + */ export function makeLoader(mappings: NodeMapping[] = defaultMapping){ const fn : LoadNodeCallback = async function ({node, sourceId}, load){ for(const mapping of mappings){ diff --git a/test/multi-entry/snapshots/test.js.snap b/test/multi-entry/snapshots/test.js.snap index c12e1c9e80d282bd250580e09cdb329371e2392e..234d8de49a8a80895c8317c10e970d90446e013f 100644 GIT binary patch literal 1757 zcmV<31|s=ERzVyMJ#qCHHvMkt}wQnH-b)rtg0tPnem z?Kp0M7+C{a?hd6@xUfaIHbKlA3jZ|A+8$L&_fHQ)5#`4bE5pu^sD_B(;S%y{4(*giM9 z{;nJN?>x3FBQWlLXFHD~#7CNtCa(jy1>ki6CIAlL0Kl&S{0_kH0hFcjS*buh&p42z z0X0264M~PH0jVTOe~k>5BHUyau$+rYK7LtDvWFaI!5#)GC$~izP z3hxT_9MH@G|HuK~=74g(@6Gt_)*dqhDHoG7Gc%#eN*;JI58TNE@8*HOB~^+kmA{Vx zACCc_j{#}{xL!!8Or%sE6@fn#fe(tnS4AK{kx-dTseCvId^8DszXbfO1Z%@l--(CZ+P#H1N$dAkP3lp8@zxLS=ST zG<{|L4MkOJs#+U%NQm5zWtuJz7!QPK zKRL&wQ|GCC>RcG&h7&Gzzp6M<8hvG5p_JaM-lViyZHk|lD1E7VgVGz-yOiG5C~f{^ zvwEA-+e7STEWJhPR!C`@rYXIrPRNg={oCAPZ>ufWI#7Mnv%A5Hy5}#izF@VDc6;q9 z^Ha-Z=I7KkGt<@WMk!miSl5q)h7%bX-3^>h((;L!ZSQk4uw70jr+{8QmUfd#*!tW#D$VtM2*wF>3L` zDYfC4i@Ya@wtQ-$iO``&a0+!K_ z0G|Np+GYgU5T$o0y%Qml(q?y4(`d7KFOm-t8}q9srDjCkr1a(xo@3+T+%rJ+OcD%F z3f)K2hEQ*8>@ve@$Rb`FwINzyEF#09Wj`RcRaZpFmBvQRvL6g_BP^2Opv&rt<68S2 zrZfimCoN+5N9iPe7*rw@EU&DtURiCucvao=E1E24;#D4kYagwOCii6dNkNibhR$?W z$Q!kYnclzenf0v0IT4sq1G2nP3xmB;3lnl`@y*qx{&5|Lv`!XTrz)N#QYUZRU#d5v zkg<+xbI!c$fzu&%vOSW|#*Kj?`nDf< zHs8^=3G+=u#7k9rD!I4>lUkXfYddX7)r zHmTS_C5a+25(!!-mkz~VdP4%+n%o=dCE~pcY#rNJBmj1%u3|c&6gCr==Khn-L^;Fn zXI!HaE2JvY(Ybz>#^EF+Mh9{dibuzEj72>Lqb|^>9}mYEkHdh}GZ8s}oY(`Sonv`B^#@wr0 zRcDh@r_T+o4S1`YN8@<%)-&q7pPOde{c23lrD=)0A zthHC#+4bg}<>K^gEuGnuCr#$-(g|JiDeI=rrDL_SkEt_vvL`gM=g7L=PrI(1y%F6y zXHOZ6h(~ooDz@f;-8taV9FQvm-zx)`%fM^p{yYBU-2wQdeDY?X_*NNsSO)$q{^x;r z=YjX;fsg0Y+NIPb!FUpQBDaIVT-J;EC>RH!7)-qU>|P^u5eD&kQV>|+aO}+ literal 1703 zcmV;Y23Yw)RzV{!Q5`9fNFa&^ zABdWusIMJ|ApK0fDO;SNK#bU8k%%LsD zeTd*^fX9HRfRVV*WISNGUOj@Aw0pN4MkAOe?CW(MaehMKT zAOJoBJecyCBm*W-6A1kYppyu_3(%52lj&ZQNjrTB(22~FoJOaqQAw9^=K)K)W?D>z zDKP0wp_r^cVx9KQAYN5!_^hb9vv^UIRYl7Mtr0avQNK?k)X^LP zcRp`p&MfT5*yIjNCJKY+@=CwCWP?MK*@V0GPAWPb`3r5cx3FOU15WR zupH}Hn(WFIHk-}C+dCnma@Ex->6!&Q2T^S&r%yTsEs#$^BaSp!IT;E>)kz~fu{_UT z=FaeZi7SzhlRSTt+vNF8?jp}$%tOD0OQAVllsXRIZBE>e3$blZ%ArXU8!^(^aoKDVvvZ-E@?^iFBN9S!&Ji zd0=L%4NbCOevIwqEpVOAYzrC#F9TZ*Lt_Ni&?}1es=z{WTaaIlb^1FmMRk6_6&*^9 zWr+0_Q#EuI3_H`V*I^n$A2WC0fSGr-_UK-7ceJ#uOAQrPmA!_o^%^GPT60rQrwmX@ zWjOEBG9EAeiJAv80u2c*oex4jLeQl(hp;wF&-46whmnB#8W@#ImmPhZv2H&n@x0_n z!2UBHKD*BCwtZlA(ocrxrS5%dm6#V-x3DM|X%es1oJS@cb42@5R&FthTwqDa+2U#r zo;|$|7a6Nr#|2i^SbQS|s=ZyiA%$%l z*EsS^0`baK*utHV;aXPFG;C~uW9TXOV$QW;j%G`$JyXPLv>uyHYxXkz9zW;Bdt z#?l!J!$?9I#sMXv%wSUzNxZUbE6Z$PO~Q<|rI-vMDkG#o4VyxWSSp%SYsi=pYc&G> zHaM*6hH5f;l}Ra9%FiP5L=vg0dWQUTw z;-qhKA*6IP%I%6d#EHnR1l=Q#TN9jmV|UnXL?ZR({dP}RvDbrBlepzIo?l*bv`#?# ziIUrUe4SIFS8ey&-a37YYu#tJ@$5dGyy(4Gr}V#Hox+OKF3JtNs_7aovV&`l|2RkL z&GONug{A63HN4*JvRv$(t<2CfdER7Rq6VCjcNjOYFZHzw-=>B>$qqQk?jq|#JM98H z{6TbmmuE^>h5S_GRICD}X$x>45Sc;fCBPBDg_-t${PBw&@=+uHn}OI((7Fxyl6=o1 zbPwq9l&h2Y)9=B*v*l-ZgZ?n z8oMLq>6q$elW*#=Hlyw5QSz}~9)YEss@8I=A2yusc9ZdR_PJzNZKBX!DO)G_{ x17yK&Jmy00a>8{N2Vdrd+|7mind~|Kh3Z6}q2UjJ|HHo`^xsSQ4Ec~30037cJ-+|| diff --git a/test/templating/snapshots/test.js.snap b/test/templating/snapshots/test.js.snap index 107f9380a6b6cb0f77f5dd4824eeccca8bed6909..c58d00f126f39e1999464daebc0d99377a8bf894 100644 GIT binary patch literal 792 zcmV+z1LyofRzVSP&O6V0 zx?|Nn`>}uWS_HMAF7~S2t<;6Zn|{rAdBd-Ifq!yZsqlbr>aP?eAs><=>J0#S0Jj0G z0hl2AIMGkJ9NhhykL23=y&wk%tI*A-^OXzLUd*OsV|<@Dsoh0nP~Ufwa=< zYu28y1Cr8fM*JDrT`z67$wz9839p2(wHEL zEAmIQaiZE@MYJcv_FO+OEwf}!O_vrYEgm@Boh%q~-K&di-P@hArlzM0h9M3bUNbO{ zOv^kj7`fav)A#n9wpitjM$O%Quzt4`(P!-W9X>a=U}yLItiu~dOhIa=Ru}iU(@}A` zp9eBZ$Ws+)V-$xsVtMpv|8SZd`NPjjz{M)A4ptwdNgaa|cFWPm6W?$|pNOVk^IV$0 zo}qF(ny3An&!G*v0Yf zW~~vJe$y@uDw`P`HbjX!US+>7=wdM!;iCkGQOt$uin&mabZ_#l3cOc=?<%mZ0lo%2 z*MK)#%f**A+KwVhpON+W$;#uq&_cbZ-L86j;m-f7edyLt+PPb`@V14^U%Qr*t=k+1 zhV}EnXzw+TNl&(X6wX!oO7*mCwWnpLNMcq8=JnpbuEjz3bzmz7(&NpafDB719i_wF W1|1BUz1X1xdh0JG>j6kg8_)!7w@t=M2u5rIdI0e- zyE~=D{gvIpKnNzpt6n{M!L#8n@L=>};y>X@uNqI@e6!n@c3Uw~C;4{Y%=_M(H}mGb zlcr&N=Hu}AHREk=v)vYTEt?rM2-~4c{jlZn@c6{CD5sn9t2D|YF>nrNZot0`xD99k zE@OELOC$*B0mfY^pU)$#Ae=_{BF0;>F-R}OA4lRlA*O^&=?92E0f!i&Q@{t@aVs~B zU1oBe>WPz+laa}1pnSoR2ebrOPbEyULncNVp%&m7;1uvNoiND_nv5fyK{yYb)D>|M zX$ogd&tlyPGd(xts-afZnb~S>+MwK_?sP>F>z>Vuwzo55%*@VK6ou{kUcl8uU>{YK zQt6r+dV7J%)~N5d-JJ*PcdN1aoVnPf3kyqTaW^bF)K?M_wD zkj=sxA@xFCd{ziqDXbE*TG$|DqXJ7eZxtGZH2T!_9($RPs)|l9$63g$8r5Q@UOFS{hG!l0*@R}$_PH7cW_48B zRDR&Is^)ms9%QzrmtubGKvDEkSv9`GHoEg=*Fo&(-UohrVt(XA+) z9x7xxd9&jB&Ml$A+wNw)yKv|K>N(bgX=|ku&+x=(tRLoB}j6z`9q%{6QT4X9qTX9(Uke~D|AF} N{RLixTKCHa008Yuen|iT