@bartificer/linkify 2.4.0 → 2.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +135 -35
  2. package/dist/index.js +1 -1
  3. package/docs/LinkData.class.mjs.html +28 -53
  4. package/docs/LinkTemplate.class.mjs.html +29 -33
  5. package/docs/Linkifier.class.mjs.html +46 -59
  6. package/docs/PageData.class.mjs.html +54 -69
  7. package/docs/defaults.mjs.html +22 -2
  8. package/docs/docdash-overrides.css +9 -3
  9. package/docs/externals.jsdoc.html +6 -2
  10. package/docs/global.html +1276 -0
  11. package/docs/index.html +114 -45
  12. package/docs/index.js.html +7 -3
  13. package/docs/mermaid-init.js +21 -0
  14. package/docs/module-cheerio.html +6 -2
  15. package/docs/module-defaults.html +100 -5
  16. package/docs/module-link-data.LinkData.html +81 -212
  17. package/docs/module-link-data.html +8 -4
  18. package/docs/module-link-template.LinkTemplate.html +71 -96
  19. package/docs/module-link-template.html +8 -4
  20. package/docs/module-linkifier.Linkifier.html +103 -376
  21. package/docs/module-linkifier.html +6 -2
  22. package/docs/module-linkify.html +7 -3
  23. package/docs/module-mustache.html +6 -2
  24. package/docs/module-node-fetch.html +6 -2
  25. package/docs/module-page-data.PageData.html +224 -202
  26. package/docs/module-page-data.html +8 -4
  27. package/docs/module-title-case.html +6 -2
  28. package/docs/module-urijs.html +6 -2
  29. package/docs/module-url-slug.html +6 -2
  30. package/docs/module-utilities.html +74 -24
  31. package/docs/typedefs.jsdoc.html +145 -0
  32. package/docs/utilities.mjs.html +36 -23
  33. package/package.json +3 -2
  34. package/src/LinkData.class.mjs +22 -51
  35. package/src/LinkTemplate.class.mjs +23 -31
  36. package/src/Linkifier.class.mjs +40 -57
  37. package/src/PageData.class.mjs +48 -67
  38. package/src/defaults.mjs +16 -0
  39. package/src/index.js +1 -1
  40. package/src/typedefs.jsdoc +52 -0
  41. package/src/utilities.mjs +30 -21
package/docs/typedefs.jsdoc.html ADDED
@@ -0,0 +1,145 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+
5
+ <meta charset="utf-8">
6
+ <title>typedefs.jsdoc - @bartificer/linkify Documentation</title>
7
+
8
+ <meta name="description" content="Documentation for the @bartificer/linkify package" />
9
+
10
+ <meta name="keywords" content="documentation, linkify, link, template, javascript, generator, npm, module, package" />
11
+ <meta name="keyword" content="documentation, linkify, link, template, javascript, generator, npm, module, package" />
12
+
13
+
14
+
15
+ <meta property="og:title" content="@bartificer/linkify"/>
16
+ <meta property="og:type" content="website"/>
17
+ <meta property="og:image" content=""/>
18
+ <meta property="og:site_name" content="@bartificer/linkify Documentation"/>
19
+ <meta property="og:url" content="https://bartificer.github.io/linkify/"/>
20
+
21
+ <script src="scripts/prettify/prettify.js"></script>
22
+ <script src="scripts/prettify/lang-css.js"></script>
23
+ <!--[if lt IE 9]>
24
+ <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
25
+ <![endif]-->
26
+ <link type="text/css" rel="stylesheet" href="styles/prettify.css">
27
+ <link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
28
+ <script src="scripts/nav.js" defer></script>
29
+
30
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
31
+ </head>
32
+ <body>
33
+
34
+ <input type="checkbox" id="nav-trigger" class="nav-trigger" />
35
+ <label for="nav-trigger" class="navicon-button x">
36
+ <div class="navicon"></div>
37
+ </label>
38
+
39
+ <label for="nav-trigger" class="overlay"></label>
40
+
41
+ <nav class="wrap">
42
+
43
+ <input type="text" id="nav-search" placeholder="Search" />
44
+
45
+
46
+ <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/bartificer/linkify" target="_blank" >On GitHub</a></h2><h2><a href="https://bartificer.net/" target="_blank" >Bartificer Creations</a></h2><h3>Modules</h3><ul><li><a href="module-defaults.html">defaults</a><ul class='members'><li data-type='member'><a href="module-defaults.html#.linkTemplates">linkTemplates</a></li><li data-type='member'><a href="module-defaults.html#.smallWords">smallWords</a></li><li data-type='member'><a href="module-defaults.html#.speciallyCapitalisedWords">speciallyCapitalisedWords</a></li></ul><ul class='methods'><li data-type='method'><a href="module-defaults.html#.dataTransformer">dataTransformer</a></li></ul></li><li><a href="module-link-data.html">link-data</a></li><li><a href="module-link-template.html">link-template</a></li><li><a href="module-linkifier.html">linkifier</a></li><li><a href="module-linkify.html">linkify</a><ul class='members'><li data-type='member'><a href="module-linkify.html#.LinkData">LinkData</a></li><li data-type='member'><a href="module-linkify.html#.LinkTemplate">LinkTemplate</a></li><li data-type='member'><a href="module-linkify.html#.Linkifier">Linkifier</a></li><li data-type='member'><a href="module-linkify.html#.PageData">PageData</a></li><li data-type='member'><a href="module-linkify.html#.VERSION">VERSION</a></li><li data-type='member'><a href="module-linkify.html#.default">default</a></li><li data-type='member'><a href="module-linkify.html#.linkify">linkify</a></li></ul></li><li><a href="module-page-data.html">page-data</a></li><li><a href="module-utilities.html">utilities</a><ul class='methods'><li data-type='method'><a href="module-utilities.html#.batchFixCustomWordCases">batchFixCustomWordCases</a></li><li data-type='method'><a href="module-utilities.html#.escapeRegex">escapeRegex</a></li><li data-type='method'><a href="module-utilities.html#.extractSlug">extractSlug</a></li><li data-type='method'><a href="module-utilities.html#.regulariseWhitespace">regulariseWhitespace</a></li><li data-type='method'><a href="module-utilities.html#.stripQueryString">stripQueryString</a></li><li data-type='method'><a href="module-utilities.html#.stripUTMParameters">stripUTMParameters</a></li><li data-type='method'><a href="module-utilities.html#.toTitleCase">toTitleCase</a></li></ul></li></ul><h3>Classes</h3><ul><li><a href="module-link-data.LinkData.html">LinkData</a><ul class='methods'><li data-type='method'><a href="module-link-data.LinkData.html#asPlainObject">asPlainObject</a></li></ul></li><li><a href="module-link-template.LinkTemplate.html">LinkTemplate</a><ul class='methods'><li data-type='method'><a href="module-link-template.LinkTemplate.html#addFilter">addFilter</a></li><li data-type='method'><a href="module-link-template.LinkTemplate.html#filtersFor">filtersFor</a></li></ul></li><li><a href="module-linkifier.Linkifier.html">Linkifier</a><ul class='methods'><li data-type='method'><a href="module-linkifier.Linkifier.html#fetchPageData">fetchPageData</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#generateLink">generateLink</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#getTemplate">getTemplate</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#getTemplateNameForDomain">getTemplateNameForDomain</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#getTransformerForDomain">getTransformerForDomain</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#registerDefaultTemplateMapping">registerDefaultTemplateMapping</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#registerTemplate">registerTemplate</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#registerTransformer">registerTransformer</a></li></ul></li><li><a href="module-page-data.PageData.html">PageData</a><ul class='methods'><li data-type='method'><a href="module-page-data.PageData.html#addSecondaryHeading">addSecondaryHeading</a></li><li data-type='method'><a href="module-page-data.PageData.html#addTopLevelHeading">addTopLevelHeading</a></li><li data-type='method'><a href="module-page-data.PageData.html#asPlainObject">asPlainObject</a></li><li data-type='method'><a href="module-page-data.PageData.html#h1">h1</a></li><li data-type='method'><a href="module-page-data.PageData.html#h2">h2</a></li></ul></li></ul><h3>Global</h3><ul><li><a href="global.html#dataTransformer">dataTransformer</a></li><li><a href="global.html#plainLinkInformationObject">plainLinkInformationObject</a></li><li><a href="global.html#plainPageInformationObject">plainPageInformationObject</a></li><li><a href="global.html#templateFieldFilterFunction">templateFieldFilterFunction</a></li><li><a href="global.html#templateFieldFilterTuple">templateFieldFilterTuple</a></li></ul><h3>Externals</h3><ul><li><a href="module-cheerio.html">cheerio</a></li><li><a href="module-mustache.html">mustache</a></li><li><a href="module-node-fetch.html">node-fetch</a></li><li><a href="module-title-case.html">title-case</a></li><li><a href="module-urijs.html">urijs</a></li><li><a href="module-url-slug.html">url-slug</a></li></ul>
47
+
48
+ </nav>
49
+
50
+ <div id="main">
51
+
52
+ <h1 class="page-title">typedefs.jsdoc</h1>
53
+
54
+
55
+
56
+
57
+
58
+
59
+
60
+ <section>
61
+ <article>
62
+ <pre class="prettyprint source linenums"><code>/**
63
+ * Functions for converting information extracted from a web page into the information used to render links.
64
+ * @callback dataTransformer
65
+ * @param {module:page-data.PageData} pData - The web page data to be transrormed to link data.
66
+ * @returns {module:link-data.LinkData} The link information derived from the page data.
67
+ */
68
+
69
+ /**
70
+ * Functions for filtering template field values before their use to render links. Arbitrarily many of these functions can be added to a template in order to filter individual fields, or all fields.
71
+ * @callback templateFieldFilterFunction
72
+ * @param {string} originalString - the original value for the field to be filtered.
73
+ * @returns {string} the filtered version of the original string.
74
+ */
75
+
76
+ /**
77
+ * A tupple (array of length exactly two) for assigning a field filter to a template.
78
+ * @typedef {Array} templateFieldFilterTuple
79
+ * @property {"all"|"url"|"text"|"description"} 0 - the property the filter should be applied to.
80
+ * @property {templateFieldFilterFunction} 1 - the filter function to apply.
81
+ */
82
+
83
+ /**
84
+ * A plain object represeting the information about about link that can get utilised in a template.
85
+ *
86
+ * Note that the `uri` could contain more fields - it's initialised with output from the `URI.parse()` function from the `URI` module.
87
+ * @typedef {Object} plainLinkInformationObject
88
+ * @property {string} url - the URL for the link.
89
+ * @property {string} text - the text for the link.
90
+ * @property {string} description - a description for the link.
91
+ * @property {Object} uri - the URL's components
92
+ * @property {string} url.hostname - the hostname part of the URL.
93
+ * @property {string} url.path - the path part of the UL, `/` for an empty path.
94
+ * @property {boolean} url.hasPath - whether or not the URL has a path, note that `/` is considered no path.
95
+ * @see {@link https://medialize.github.io/URI.js/docs.html#static-parse}
96
+ */
97
+
98
+ /**
99
+ * A plain object representing the infomration extracted from a web page.
100
+ *
101
+ * Note that the `uri` could contain more fields - it's initialised with output from the `URI.parse()` function from the `URI` module.
102
+ * @typedef {Object} plainPageInformationObject
103
+ * @property {string} url - the page's URL.
104
+ * @property {string} title - the page's title.
105
+ * @property {string[]} topLevelHeadings - the text from the page's `h1` tags.
106
+ * @property {string[]} secondaryHeadings - text from the page's `h2` tags.
107
+ * @property {string} mainHeading - the text from the most semantically important heading that exists in the page.
108
+ * @property {Object} uri - the URL's components
109
+ * @property {string} url.hostname - the hostname part of the URL.
110
+ * @property {string} url.path - the path part of the UL, `/` for an empty path.
111
+ * @property {boolean} url.hasPath - whether or not the URL has a path, note that `/` is considered no path.
112
+ * @see {@link https://medialize.github.io/URI.js/docs.html#static-parse}
113
+ */</code></pre>
114
+ </article>
115
+ </section>
116
+
117
+
118
+
119
+
120
+
121
+
122
+ </div>
123
+
124
+ <br class="clear">
125
+
126
+ <footer>
127
+ Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Wed Apr 15 2026 17:49:51 GMT+0100 (Irish Standard Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
128
+ </footer>
129
+
130
+ <script>prettyPrint();</script>
131
+ <script src="scripts/polyfill.js"></script>
132
+ <script src="scripts/linenumber.js"></script>
133
+
134
+ <script src="scripts/search.js" defer></script>
135
+
136
+
137
+
138
+ <link type="text/css" rel="stylesheet" href="./docdash-overrides.css">
139
+
140
+ <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
141
+
142
+ <script src="./mermaid-init.js"></script>
143
+
144
+ </body>
145
+ </html>
package/docs/utilities.mjs.html CHANGED
@@ -43,7 +43,7 @@
43
43
  <input type="text" id="nav-search" placeholder="Search" />
44
44
 
45
45
 
46
- <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/bartificer/linkify" target="_blank" >On GitHub</a></h2><h2><a href="https://bartificer.net/" target="_blank" >Bartificer Creations</a></h2><h3>Modules</h3><ul><li><a href="module-defaults.html">defaults</a><ul class='members'><li data-type='member'><a href="module-defaults.html#.linkTemplates">linkTemplates</a></li><li data-type='member'><a href="module-defaults.html#.smallWords">smallWords</a></li><li data-type='member'><a href="module-defaults.html#.speciallyCapitalisedWords">speciallyCapitalisedWords</a></li></ul></li><li><a href="module-link-data.html">link-data</a></li><li><a href="module-link-template.html">link-template</a></li><li><a href="module-linkifier.html">linkifier</a></li><li><a href="module-linkify.html">linkify</a><ul class='members'><li data-type='member'><a href="module-linkify.html#.LinkData">LinkData</a></li><li data-type='member'><a href="module-linkify.html#.LinkTemplate">LinkTemplate</a></li><li data-type='member'><a href="module-linkify.html#.Linkifier">Linkifier</a></li><li data-type='member'><a href="module-linkify.html#.PageData">PageData</a></li><li data-type='member'><a href="module-linkify.html#.VERSION">VERSION</a></li><li data-type='member'><a href="module-linkify.html#.default">default</a></li><li data-type='member'><a href="module-linkify.html#.linkify">linkify</a></li></ul></li><li><a href="module-page-data.html">page-data</a></li><li><a href="module-utilities.html">utilities</a><ul class='methods'><li data-type='method'><a href="module-utilities.html#.batchFixCustomWordCases">batchFixCustomWordCases</a></li><li data-type='method'><a href="module-utilities.html#.escapeRegex">escapeRegex</a></li><li data-type='method'><a href="module-utilities.html#.extractSlug">extractSlug</a></li><li data-type='method'><a href="module-utilities.html#.regulariseWhitespace">regulariseWhitespace</a></li><li data-type='method'><a href="module-utilities.html#.stripQueryString">stripQueryString</a></li><li data-type='method'><a href="module-utilities.html#.stripUTMParameters">stripUTMParameters</a></li><li data-type='method'><a href="module-utilities.html#.toTitleCase">toTitleCase</a></li></ul></li></ul><h3>Classes</h3><ul><li><a href="module-link-data.LinkData.html">LinkData</a><ul class='methods'><li data-type='method'><a href="module-link-data.LinkData.html#asPlainObject">asPlainObject</a></li></ul></li><li><a href="module-link-template.LinkTemplate.html">LinkTemplate</a><ul class='methods'><li data-type='method'><a href="module-link-template.LinkTemplate.html#addFilter">addFilter</a></li><li data-type='method'><a href="module-link-template.LinkTemplate.html#filtersFor">filtersFor</a></li></ul></li><li><a href="module-linkifier.Linkifier.html">Linkifier</a><ul class='methods'><li data-type='method'><a href="module-linkifier.Linkifier.html#fetchPageData">fetchPageData</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#generateLink">generateLink</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#getTemplate">getTemplate</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#getTemplateNameForDomain">getTemplateNameForDomain</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#getTransformerForDomain">getTransformerForDomain</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#registerDefaultTemplateMapping">registerDefaultTemplateMapping</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#registerTemplate">registerTemplate</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#registerTransformer">registerTransformer</a></li></ul></li><li><a href="module-page-data.PageData.html">PageData</a><ul class='methods'><li data-type='method'><a href="module-page-data.PageData.html#addSecondaryHeading">addSecondaryHeading</a></li><li data-type='method'><a href="module-page-data.PageData.html#addTopLevelHeading">addTopLevelHeading</a></li><li data-type='method'><a href="module-page-data.PageData.html#asPlainObject">asPlainObject</a></li><li data-type='method'><a href="module-page-data.PageData.html#h1">h1</a></li><li data-type='method'><a href="module-page-data.PageData.html#h2">h2</a></li></ul></li></ul><h3>Externals</h3><ul><li><a href="module-cheerio.html">cheerio</a></li><li><a href="module-mustache.html">mustache</a></li><li><a href="module-node-fetch.html">node-fetch</a></li><li><a href="module-title-case.html">title-case</a></li><li><a href="module-urijs.html">urijs</a></li><li><a href="module-url-slug.html">url-slug</a></li></ul>
46
+ <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/bartificer/linkify" target="_blank" >On GitHub</a></h2><h2><a href="https://bartificer.net/" target="_blank" >Bartificer Creations</a></h2><h3>Modules</h3><ul><li><a href="module-defaults.html">defaults</a><ul class='members'><li data-type='member'><a href="module-defaults.html#.linkTemplates">linkTemplates</a></li><li data-type='member'><a href="module-defaults.html#.smallWords">smallWords</a></li><li data-type='member'><a href="module-defaults.html#.speciallyCapitalisedWords">speciallyCapitalisedWords</a></li></ul><ul class='methods'><li data-type='method'><a href="module-defaults.html#.dataTransformer">dataTransformer</a></li></ul></li><li><a href="module-link-data.html">link-data</a></li><li><a href="module-link-template.html">link-template</a></li><li><a href="module-linkifier.html">linkifier</a></li><li><a href="module-linkify.html">linkify</a><ul class='members'><li data-type='member'><a href="module-linkify.html#.LinkData">LinkData</a></li><li data-type='member'><a href="module-linkify.html#.LinkTemplate">LinkTemplate</a></li><li data-type='member'><a href="module-linkify.html#.Linkifier">Linkifier</a></li><li data-type='member'><a href="module-linkify.html#.PageData">PageData</a></li><li data-type='member'><a href="module-linkify.html#.VERSION">VERSION</a></li><li data-type='member'><a href="module-linkify.html#.default">default</a></li><li data-type='member'><a href="module-linkify.html#.linkify">linkify</a></li></ul></li><li><a href="module-page-data.html">page-data</a></li><li><a href="module-utilities.html">utilities</a><ul class='methods'><li data-type='method'><a href="module-utilities.html#.batchFixCustomWordCases">batchFixCustomWordCases</a></li><li data-type='method'><a href="module-utilities.html#.escapeRegex">escapeRegex</a></li><li data-type='method'><a href="module-utilities.html#.extractSlug">extractSlug</a></li><li data-type='method'><a href="module-utilities.html#.regulariseWhitespace">regulariseWhitespace</a></li><li data-type='method'><a href="module-utilities.html#.stripQueryString">stripQueryString</a></li><li data-type='method'><a href="module-utilities.html#.stripUTMParameters">stripUTMParameters</a></li><li data-type='method'><a href="module-utilities.html#.toTitleCase">toTitleCase</a></li></ul></li></ul><h3>Classes</h3><ul><li><a href="module-link-data.LinkData.html">LinkData</a><ul class='methods'><li data-type='method'><a href="module-link-data.LinkData.html#asPlainObject">asPlainObject</a></li></ul></li><li><a href="module-link-template.LinkTemplate.html">LinkTemplate</a><ul class='methods'><li data-type='method'><a href="module-link-template.LinkTemplate.html#addFilter">addFilter</a></li><li data-type='method'><a href="module-link-template.LinkTemplate.html#filtersFor">filtersFor</a></li></ul></li><li><a href="module-linkifier.Linkifier.html">Linkifier</a><ul class='methods'><li data-type='method'><a href="module-linkifier.Linkifier.html#fetchPageData">fetchPageData</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#generateLink">generateLink</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#getTemplate">getTemplate</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#getTemplateNameForDomain">getTemplateNameForDomain</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#getTransformerForDomain">getTransformerForDomain</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#registerDefaultTemplateMapping">registerDefaultTemplateMapping</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#registerTemplate">registerTemplate</a></li><li data-type='method'><a href="module-linkifier.Linkifier.html#registerTransformer">registerTransformer</a></li></ul></li><li><a href="module-page-data.PageData.html">PageData</a><ul class='methods'><li data-type='method'><a href="module-page-data.PageData.html#addSecondaryHeading">addSecondaryHeading</a></li><li data-type='method'><a href="module-page-data.PageData.html#addTopLevelHeading">addTopLevelHeading</a></li><li data-type='method'><a href="module-page-data.PageData.html#asPlainObject">asPlainObject</a></li><li data-type='method'><a href="module-page-data.PageData.html#h1">h1</a></li><li data-type='method'><a href="module-page-data.PageData.html#h2">h2</a></li></ul></li></ul><h3>Global</h3><ul><li><a href="global.html#dataTransformer">dataTransformer</a></li><li><a href="global.html#plainLinkInformationObject">plainLinkInformationObject</a></li><li><a href="global.html#plainPageInformationObject">plainPageInformationObject</a></li><li><a href="global.html#templateFieldFilterFunction">templateFieldFilterFunction</a></li><li><a href="global.html#templateFieldFilterTuple">templateFieldFilterTuple</a></li></ul><h3>Externals</h3><ul><li><a href="module-cheerio.html">cheerio</a></li><li><a href="module-mustache.html">mustache</a></li><li><a href="module-node-fetch.html">node-fetch</a></li><li><a href="module-title-case.html">title-case</a></li><li><a href="module-urijs.html">urijs</a></li><li><a href="module-url-slug.html">url-slug</a></li></ul>
47
47
 
48
48
  </nav>
49
49
 
@@ -66,12 +66,16 @@
66
66
  */
67
67
 
68
68
  /**
69
- * This module provides utility functions which are both used by the core code, and, available for use by users when defining link data transformers and link templates.
69
+ * Utility functions, intended both for use within the core link generation code, and, by users defining their own custom templates, transformer functions, and filter functions.
70
+ *
71
+ * This module is exposed to end-users as {@link module:linkifier.Linkifier#utilities} and {@link module:linkifier.Linkifier#util}.
70
72
  * @module utilities
71
- * @requires module:defaults
73
+ * @requires defaults
72
74
  * @requires module:urijs
73
75
  * @requires module:url-slug
74
76
  * @requires module:title-case
77
+ * @see {@link module:linkifier.Linkifier#utilities} for the short-cut to this module exposed on the Linkifier class.
78
+ * @see {@link module:linkifier.Linkifier#util} for the short-cut to this module exposed on the Linkifier class.
75
79
  */
76
80
  import * as defaults from './defaults.mjs';
77
81
  import URI from 'urijs';
@@ -82,27 +86,27 @@ import * as titleCase from 'title-case';
82
86
  * Regularise white space by replacing all sequences of whitespace characters with a single space and trimming leading and trailing whitespace.
83
87
  *
84
88
  * @param {string} text
85
- * @return {string}
89
+ * @returns {string}
86
90
  */
87
91
  export function regulariseWhitespace(text){
88
92
  return String(text).replace(/[\s\n]+/g, ' ').trim();
89
93
  };
90
94
 
91
95
  /**
92
- * Strip the query string from a URL.
96
+ * Strip the query string from a URL, if present.
93
97
  *
94
- * @param {string} url
95
- * @return {string}
98
+ * @param {string} url - a URL with our without a query string.
99
+ * @returns {string} the original URL with the query string removed, if it was present.
96
100
  */
97
101
  export function stripQueryString(url){
98
102
  return URI(url).query('').toString();
99
103
  };
100
104
 
101
105
  /**
102
- * Remove UTM parameters from the query string in a URL.
106
+ * Remove UTM parameters from the query string in a URL, if present.
103
107
  *
104
- * @param {string} url
105
- * @return {string}
108
+ * @param {string} url - a URL with or without UTM parameters in the query string.
109
+ * @returns {string} the original URL with the UTM parameters removed, if they were present, but with any other query parameters preserved.
106
110
  * @see {@link https://en.wikipedia.org/wiki/UTM_parameters}
107
111
  */
108
112
  export function stripUTMParameters(url){
@@ -115,7 +119,7 @@ export function stripUTMParameters(url){
115
119
  * _**Note:** this is not a standard Javascript feature as of April 2026, though it is coming in future versions of Javascript._
116
120
  *
117
121
  * @param {string} str - the string to escape.
118
- * @returns {string}
122
+ * @returns {string} the escaped string, ready for use in a regular expression.
119
123
  * @see {@link https://stackoverflow.com/a/3561711/174985}
120
124
  */
121
125
  export function escapeRegex(str) {
@@ -123,11 +127,11 @@ export function escapeRegex(str) {
123
127
  }
124
128
 
125
129
  /**
126
- * Batch-customise word casings in a string. E.g. force `fbi` to `FBI`, `ios` to `iOS`, etc..
130
+ * Batch-fix words with special capitalisations in a string. E.g. force `fbi` to `FBI`, `ios` to `iOS`, etc..
127
131
  *
128
- * @param {string} str - the string to apply the replacemnts to.
129
- * @param {string[]} [words] - an array of words in their desired capitalisations. Defaults to the default list of custom capitalisations.
130
- * @returns {string}
132
+ * @param {string} str - the string to apply the capitalisation corrections to.
133
+ * @param {string[]} [words] - the list of words with special capitalisations. Defaults to the default list {@link module:defaults.speciallyCapitalisedWords}.
134
+ * @returns {string} the original string with all occurrences of the words in the list capitalised as per the word list. All other capitatlisations will be left un-changed.
131
135
  * @see {@link module:defaults.speciallyCapitalisedWords} for the default list of custom capitalisations.
132
136
  */
133
137
  export function batchFixCustomWordCases(str, words){
@@ -162,12 +166,15 @@ export function batchFixCustomWordCases(str, words){
162
166
  /**
163
167
  * Convert a string to title case, with some custom capitalisations.
164
168
  *
169
+ * This functions uses the {@link module:title-case} to perform the initial title-caseing, and then applies the custom capitalisations to fix any words with unusual capitalisation requirements.
170
+ * All words this mododule defies as being so-called *small words* (e.g., "the", "a" &amp; "an") are preserved in lower case, as well as the additional words defined in {@link module:defaults.smallWords}.
171
+ *
165
172
  * @param {string} str - the string to convert to title case.
166
- * @param {string[]} [words] - a list of words with custom capitalisations to correct after title-casing. Defaults to the default list of custom capitalisations.
167
- * @return {string}
173
+ * @param {string[]} [words] - a list of words with custom capitalisations to correct after title-casing. Defaults to {@link module:defaults.speciallyCapitalisedWords}.
174
+ * @returns {string} the original string converted to title case, with the custom capitalisations applied.
168
175
  * @see {@link module:defaults.speciallyCapitalisedWords} for the default list of custom capitalisations.
169
- * @see {@link module:title-case} for the Title Case module who's titleCase function is used to convert to title case, and which has its own default list of small words that are preserved in lower case.
170
- * @see {@link module:defaults.smallWords} for the additional list of small words that are preserved in lower case by the title-casing function.
176
+ * @see {@link module:title-case} for the Title Case module who's `titleCase()` function is used to convert to title case, and which has its own default list of small words that are preserved in lower case.
177
+ * @see {@link module:defaults.smallWords} for the additional list of small words that are preserved in lower case.
171
178
  */
172
179
  export function toTitleCase(str, words){
173
180
  // coerce the first argument to a string
@@ -192,9 +199,11 @@ export function toTitleCase(str, words){
192
199
  /**
193
200
  * Extract the slug from a URL and convert it to a title-case string.
194
201
  *
195
- * @param {string} url
196
- * @param {string[]} [words] - a list of words with custom capitalisations to correct after title-casing.
197
- * @return {string}
202
+ * @param {string} url - the URL to extract the slug from. The slug is taken to be the last segment of the path, with any file extension removed, and with the query string and fragment ignored.
203
+ * @param {string[]} [words] - a list of words with custom capitalisations to correct after title-casing. Defaults to {@link module:defaults.speciallyCapitalisedWords}.
204
+ * @returns {string} the slug extracted from the URL, converted to title case, with the custom capitalisations applied.
205
+ * @see {@link module:defaults.speciallyCapitalisedWords} for the default list of custom capitalisations.
206
+ * @see {@link toTitleCase} for the function used for the title-casing.
198
207
  */
199
208
  export function extractSlug(url, words){
200
209
  // TO DO - add validation
@@ -253,7 +262,7 @@ export function extractSlug(url, words){
253
262
  <br class="clear">
254
263
 
255
264
  <footer>
256
- Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Apr 13 2026 16:45:07 GMT+0100 (Irish Standard Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
265
+ Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Wed Apr 15 2026 17:49:51 GMT+0100 (Irish Standard Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
257
266
  </footer>
258
267
 
259
268
  <script>prettyPrint();</script>
@@ -266,5 +275,9 @@ export function extractSlug(url, words){
266
275
 
267
276
  <link type="text/css" rel="stylesheet" href="./docdash-overrides.css">
268
277
 
278
+ <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
279
+
280
+ <script src="./mermaid-init.js"></script>
281
+
269
282
  </body>
270
283
  </html>
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@bartificer/linkify",
3
- "version": "2.4.0",
4
- "description": "An module for converting URLs into pretty links in any format.",
3
+ "version": "2.4.1",
4
+ "description": "A module for converting URLs into pretty links in any format.",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
@@ -43,6 +43,7 @@
43
43
  "clean-jsdoc-theme": "^4.3.0",
44
44
  "docdash": "^2.0.2",
45
45
  "jsdoc": "^4.0.5",
46
+ "marked": "^18.0.0",
46
47
  "webpack": "^5.105.4",
47
48
  "webpack-cli": "^7.0.2"
48
49
  }
package/src/LinkData.class.mjs CHANGED
@@ -1,29 +1,28 @@
1
1
  /**
2
- * @file The definition of the class representing a link.
2
+ * @file Data model for link information.
3
3
  * @author Bart Busschots <opensource@bartificer.ie>
4
4
  * @license MIT
5
5
  */
6
6
 
7
7
  /**
8
- * This module provides as class for representing the information that can be used when rendering a link.
8
+ * This module provides the class for representing the information that can be used to render a link.
9
9
  * @module link-data
10
10
  * @requires module:urijs
11
11
  */
12
12
  import {default as URI} from 'urijs';
13
13
 
14
14
  /**
15
- * A class for representing the information about a link, in the abstract.
15
+ * The information that can be used to render a link.
16
+ *
17
+ * Instances of this class are created from the information extracted from web pages by data transformers.
18
+ * @see {@link dataTransformer} for details of how instances of this class are created.
16
19
  */
17
20
  export class LinkData {
18
21
  /**
19
- * This constructor throws a {@link ValidationError} unless a valid URL is passed.
20
- *
21
- * @param {URL} url - The link's URL.
22
+ * @param {string} url - The link's URL.
22
23
  * @param {string} [text] - The link's text, defaults to the URL.
23
- * @param {string} [description] - A description for the link, defaults to
24
- * the link text.
25
- * @throws {ValidationError} A validation error is thrown if an invalid URL
26
- * is passed.
24
+ * @param {string} [description] - A description for the link, defaults to the link text.
25
+ * @throws {TypeError} A TypeError is thrown if an invalid URL is passed.
27
26
  */
28
27
  constructor(url, text, description){
29
28
  // TO DO - add validation
@@ -32,9 +31,9 @@ export class LinkData {
32
31
  * The link's URL as a URI.js object.
33
32
  *
34
33
  * @private
35
- * @type {URIObject}
34
+ * @type {module:urijs}
36
35
  */
37
- this._uri = URI();
36
+ this._uri = URI(); // throws a TypeError if the URL is invalid
38
37
 
39
38
  /**
40
39
  * The link text.
@@ -63,78 +62,50 @@ export class LinkData {
63
62
  }
64
63
 
65
64
  /**
66
- * @returns {string} a URL string
65
+ * The URL the link points to as a string.
66
+ * @type {string}
67
67
  */
68
68
  get url(){
69
69
  return this._uri.toString();
70
70
  }
71
-
72
- /**
73
- * Get or set the URL.
74
- *
75
- * @param {string} url - A new URL as a string.
76
- */
77
71
  set url(url){
78
72
  this._uri = URI(String(url)).normalize();
79
73
  }
80
74
 
81
75
  /**
82
- * Get the URL as a URI.js object.
83
- *
84
- * @returns {Object}
76
+ * The URL the link points to as a URI.js object representing the URL.
77
+ * @type {module:urijs}
78
+ * @readonly
85
79
  */
86
80
  get uri(){
87
81
  return this._uri.clone();
88
82
  }
89
83
 
90
84
  /**
91
- * @returns {string}
85
+ * The link text.
86
+ * @type {string}
92
87
  */
93
88
  get text(){
94
89
  return this._text;
95
90
  }
96
-
97
- /**
98
- * @param {string} [text] - New link text. The value will be coerced to a string and trimmed.
99
- */
100
91
  set text(text){
101
92
  this._text = String(text).trim();
102
93
  }
103
94
 
104
95
  /**
105
- * @returns {string}
96
+ * The link description.
97
+ * @type {string}
106
98
  */
107
99
  get description(){
108
100
  return this._description;
109
101
  }
110
-
111
- /**
112
- * @param {string} description
113
- */
114
102
  set description(description){
115
103
  this._description = String(description);
116
104
  }
117
105
 
118
106
  /**
119
- * Get the link data as a plain object of the form:
120
- * ```
121
- * {
122
- * url: 'http://www.bartificer.net/',
123
- * text: 'the link text',
124
- * description: 'the link description',
125
- * uri: {
126
- * hostname: 'www.bartificer.net',
127
- * path: '/',
128
- * hasPath: false
129
- * }
130
- * }
131
- * ```
132
- *
133
- * Note that the `uri` could contain more fields - it's initialised with
134
- * output from the `URI.parse()` function from the `URI` module.
135
- *
136
- * @returns {plainObject}
137
- * @see {@link https://medialize.github.io/URI.js/docs.html#static-parse}
107
+ * The link data as a plain object for use in Mustache templates and the like.
108
+ * @returns {plainLinkInformationObject} A plain object containing the link data.
138
109
  */
139
110
  asPlainObject(){
140
111
  let ans = {
package/src/LinkTemplate.class.mjs CHANGED
@@ -1,28 +1,31 @@
1
1
  /**
2
- * @file The definition of the class representing a link generation template.
2
+ * @file Link generation templates.
3
3
  * @author Bart Busschots <opensource@bartificer.ie>
4
4
  * @license MIT
5
5
  */
6
6
 
7
7
  /**
8
- * This module provides as class for representing a template used for generating links.
8
+ * This module provides as class for representing the templates used to generate links from link data objects.
9
9
  * @module link-template
10
10
  * @requires module:urijs
11
11
  */
12
12
 
13
13
  /**
14
- * A class representing the a template that can be used to render links.
14
+ * A class representing the templates used to render link data objects as actual links.
15
+ * @see {@link module:link-data.LinkData} for the data objects that are rendered with these templates.
15
16
  */
16
17
  export class LinkTemplate{
17
18
  /**
18
19
  * @param {string} templateString - A Moustache template string.
19
- * @param {Array} [filters=[]] - An optional array of filter functions.
20
- * Each element in the array should itself be an array where the first
21
- * element is a string specifying which fields the filter should be applied
22
- * to (one of `'all'`, `'url'`, `'text'`, or `'description'`), and the
23
- * second the filter function itself which should be a function that takes
24
- * a single string as an argument and returns a filtered version of that
25
- * string.
20
+ * @param {templateFieldFilterTuple[]} [filters=[]] - an optional set of filter functions to apply to some or all template fields.
21
+ * @example <caption>Example of defining a template with filters</caption>
22
+ * let template = new LinkTemplate(
23
+ * '<a href="{{{url}}}">{{{text}}}</a>',
24
+ * [
25
+ * ['url', linkify.util.stripUTMParameters],
26
+ * ['text', linkify.util.regulariseWhitespace]
27
+ * ]
28
+ * );
26
29
  */
27
30
  constructor(templateString, filters){
28
31
  // TO DO - add validation
@@ -45,7 +48,7 @@ export class LinkTemplate{
45
48
  * * `description` - filters to be applied just the link description.
46
49
  *
47
50
  * @private
48
- * @type {Object.<string, filterFunction>}
51
+ * @type {Object.<"all"|"url"|"text"|"description", templateFieldFilterFunction>}
49
52
  */
50
53
  this._filters = {
51
54
  all: [],
@@ -63,20 +66,12 @@ export class LinkTemplate{
63
66
  }
64
67
 
65
68
  /**
66
- * Get the template string.
67
- *
68
- * @returns {string}
69
+ * The Mustache template string. Will be coerced to a string with `String(templateString)`.
70
+ * @type {string}
69
71
  */
70
72
  get templateString(){
71
73
  return this._templateString;
72
74
  }
73
-
74
- /**
75
- * Set the template string. Should be in Mustache format. All values passed
76
- * will be coerced to strings.
77
- *
78
- * @param {string} templateString
79
- */
80
75
  set templateString(templateString){
81
76
  this._templateString = String(templateString);
82
77
  }
@@ -87,10 +82,9 @@ export class LinkTemplate{
87
82
  * If an invalid args are passed, the function does not save the filter or
88
83
  * throw an error, but it does log a warning.
89
84
  *
90
- * @param {string} fieldName - One of `'all'`, `'url'`, `'text'`, or
91
- * `'description'`.
92
- * @param {function} filterFn - the filter function.
93
- * @returns {LinkTemplate} Returns a reference to self to facilitate function chaining.
85
+ * @param {"all"|"url"|"text"|"description"} fieldName
86
+ * @param {templateFieldFilterFunction} filterFn - the filter function.
87
+ * @returns {module:link-template.LinkTemplate} Returns a reference to self to facilitate function chaining.
94
88
  */
95
89
  addFilter(fieldName, filterFn){
96
90
  // make sure that args are at least plausibly valid
@@ -113,13 +107,11 @@ export class LinkTemplate{
113
107
  }
114
108
 
115
109
  /**
116
- * A function get the filter functions that should be applied to any given
117
- * field.
110
+ * Get the filter functions that should be applied to any given field.
118
111
  *
119
- * @param {string} fieldName - one of `'url'`, `'text'`, or
120
- * `'description'`.
121
- * @returns {function[]} returns an array of callbacks, which may be
122
- * empty. An empty array is returned if an invalid field name is passed.
112
+ * @param {"all"|"url"|"text"|"description"} fieldName
113
+ * @returns {templateFieldFilterFunction[]} returns an array of callbacks, which may be
114
+ * empty. An empty array is also returned if an invalid field name is passed.
123
115
  */
124
116
  filtersFor(fieldName){
125
117
  fieldName = String(fieldName);