@bartificer/linkify 2.3.5 → 2.4.1

package/src/PageData.class.mjs

@@ -1,25 +1,25 @@
 /**
- * @file The definition of the class representing a web page.
+ * @file Data model for web page information.
  * @author Bart Busschots <opensource@bartificer.ie>
+ * @license MIT
  */
 
 /**
- * This module provides as class for representing the information extracted from web pages which can be used to generate the link data avaiable for rendering links.
- * @module PageData
+ * This module provides the class for representing the information that is extracted from web pages.
+ * @module page-data
  * @requires module:urijs
  */
 import {default as URI} from 'urijs';
 
 /**
- * A class representing the data extracted from web pages that can be transformed into link data for use when rendering links.
+ * The information extracted from web pages that can be used to render a link.
+ * 
+ * Instances of this class are created from the information extracted from web pages and converted to link information by data transformers before being rendered to links via templates.
+ * @see {@link dataTransformer} for details of how instances of this class are used in the link generation process.
  */
 export class PageData {
     /**
-     * This constructor throws a {@link ValidationError} unless a valid URL is passed.
-     *
-     * @param {URL} url - The page's full URL.
-     * @throws {ValidationError} A validation error is thrown if an invalid URL
-     * is passed.
+     * @param {string} url - The page's full URL.
      */
     constructor(url){
         // TO DO - add validation
@@ -28,7 +28,7 @@ export class PageData {
          * The page's URL as a URI object.
          *
          * @private
-         * @type {URIObject}
+         * @type {module:urijs}
          */
         this._uri = URI();
         
@@ -45,74 +45,73 @@ export class PageData {
          * `h1` and `h2`.
          * 
          * @private
-         * @type {plainObject}
+         * @type {Object}
+         * @property {string[]} h1 - The page's top-level headings (`h1` tags).
+         * @property {string[]} h2 - The page's secondary headings (`h2` tags).
          */
         this._headings = {
             h1: [],
             h2: []
         };
         
-        // store the URL
+        // store the URL using the public setter to ensure it's stored as a URI object
         this.url = url;
     }
     
     /**
-     * @returns {string}
+     * @type {string}
+     * @throws {TypeError} on invalid URLs.
      */
     get url(){
         return this._uri.toString();
     }
-
-    /**
-     * @param {string} url - A URL as a string.
-     * @throws {ValidationError} A validation error is thrown if an argument
-     * is passed that's not a valid URL string.
-     */
     set url(url){
         this._uri = URI(url).normalize();
     }
     
     /**
-     * @returns {Object} A URI.js object.
+     * @type {module:urijs}
+     * @readonly
      */
     get uri(){
         return this._uri.clone();
     }
     
     /**
-     * Get the domain-part of the URL as a string.
-     * 
-     * @returns {string} The domain-part of the URL.
+     * The domain-part of the URL.
+     * @type {string}
+     * @readonly
      */
     get domain(){
         return this._uri.hostname();
     }
     
     /**
-     * @returns {string} The path-part of the URL.
+     * The path-part of the URL.
+     * @type {string}
+     * @readonly
      */
     get path(){
         return this._uri.path();
     }
     
     /**
-     * @returns {string}
+     * The page's title. Values are coerced to strings with `String(title)`.
+     * @type {string}
      */
     get title(){
         return this._title;
     }
-
-    /**
-     * @param {string} title - the page's title as a string. Values passed will be coerced to strings.
-     */
     set title(title){
         this._title = String(title);
     }
     
     /**
-     * Get the page's section headings.
-     * 
-     * @returns {Object} A plain object containing arrays of strings indexed by `h1` and `h2`.
+     * The page's primary and secondary headings.
+     * @type {Object}
+     * @property {string[]} h1 - The page's top-level headings (`h1` tags).
+     * @property {string[]} h2 - The page's secondary headings (`h2` tags).
+     * @readonly
      */
     get headings(){
         let ans = {
@@ -130,8 +129,8 @@ export class PageData {
     
     /**
      * The page's top-level headings (`h1` tags).
-     *
-     * @returns {string[]}
+     * @type {string[]}
+     * @readonly
      */
     get topLevelHeadings(){
         var ans = [];
@@ -143,7 +142,8 @@ export class PageData {
 
     /**
      * An alias for `.topLevelHeadings`.
-     * @see PageData#topLevelHeadings
+     * @readonly
+     * @see {@link module:page-data.PageData#topLevelHeadings}
      */
     get h1s(){
         return this.topLevelHeadings;
@@ -151,8 +151,8 @@ export class PageData {
 
     /**
      * The page's secondary headings (`h2` tags).
-     *
-     * @returns {string[]}
+     * @type {string[]}
+     * @readonly
      */
     get secondaryHeadings(){
         var ans = [];
@@ -164,8 +164,9 @@ export class PageData {
 
     /**
      * An alias for `.secondaryHeadings`.
-     * @see PageData#secondaryHeadings
-    */
+     * @readonly
+     * @see {@link module:page-data.PageData#secondaryHeadings}
+     */
     get h2s(){
         return this.secondaryHeadings;
     }
@@ -175,8 +176,8 @@ export class PageData {
      * has `h1` tags, the first one will be used, if not, the first `h2` tag
      * will be used, and if there's none of those either, an empty string will
      * be returned.
-     * 
-     * @returns {string} Heading text as a string, or an empty string.
+     * @type {string}
+     * @readonly
      */
     get mainHeading(){
         if(this._headings.h1.length > 0){
@@ -192,7 +193,7 @@ export class PageData {
      * Add a top-level heading.
      *
      * @param {string} h1Text
-     * @returns {PageData} A reference to self to 
+     * @returns {module:page-data.PageData} A reference to self to 
      * facilitate function chaning.
      */
     addTopLevelHeading(h1Text){
@@ -205,7 +206,7 @@ export class PageData {
      * Add a seconary heading.
      *
      * @param {string} h2Text
-     * @returns {PageData} A reference to self to 
+     * @returns {module:page-data.PageData} A reference to self to 
      * facilitate function chaning.
      */
     addSecondaryHeading(h2Text){
@@ -215,27 +216,8 @@ export class PageData {
     }
 
     /**
-     * Get the page data as a plain object of the form:
-     * ```
-     * {
-     *     url: 'http://www.bartificer.net/',
-     *     title: 'the page title',
-     *     topLevelHeadings: [ 'first h1', 'second h1' ],
-     *     secondaryHeadings: [ 'first h2', 'second h2' ],
-     *     mainHeading: 'first h1',
-     *     uri: {
-     *         hostname: 'www.bartificer.net',
-     *         path: '/',
-     *         hasPath: false
-     *     }
-     * }
-     * ```
-     *
-     * Note that the `uri` could contain more fields - it's initialised with
-     * output from the `URI.parse()` function from the `URI` module.
-     * 
-     * @returns {Object} A plain object containing the page data.
-     * @see {@link https://medialize.github.io/URI.js/docs.html#static-parse}
+     * Get the page data as a plain object.
+     * @returns {plainPageInformationObject}
      */
     asPlainObject(){
         let ans = {
@@ -253,18 +235,18 @@ export class PageData {
 
 /**
  * A shortcut for `.addTopLevelHeading()`.
- *
+ * @name module:page-data.PageData#h1
  * @function
- * @see PageData#addTopLevelHeading
+ * @see {@link module:page-data.PageData#addTopLevelHeading}
  * 
  */
 PageData.prototype.h1 = PageData.prototype.addTopLevelHeading;
 
 /**
  * A shortcut for `.addSecondaryHeading()`.
- *
+ * @name module:page-data.PageData#h2
  * @function
- * @see PageData#addSecondaryHeading
+ * @see {@link module:page-data.PageData#addSecondaryHeading}
  * 
  */
 PageData.prototype.h2 = PageData.prototype.addSecondaryHeading;

package/src/defaults.mjs

@@ -1,20 +1,44 @@
 /**
- * @file The default values used throughout the linkifier classes.
+ * @file Central location for the default values used throughout the codebase.
  * @author Bart Busschots <opensource@bartificer.ie>
+ * @license MIT
  */
 
 /**
- * This module provides default values for use by the various linkifier functions and classes. These separated out for clarity, helping users decide which values to override or augment.
+ * Default values used by the various functions and classes.
+ * 
+ * The defaults are collected here for clarity, helping module users both understand the defaults, and, make informed decisions about which defaults to augment or override completely.
  * @module defaults
- * @requires module:LinkTemplate
- * @requires module:utilities
+ * @requires link-template
+ * @requires utilities
  */
 import { LinkTemplate } from './LinkTemplate.class.mjs';
 import * as utilities from "./utilities.mjs";
 
 /**
- * The collection of named link templates loaded by the Linkifier constructor.
- * @type {Object.<string, LinkTemplate>}
+ * The default link transformer. The Linkifier constructor assigns this data transformer to the root DNS name `.`, ensuring it acts as the fallback when no other domains are matched.
+ * 
+ * If the page has exactly one top-level heading, this heading is used as a the link text, otherwise the page title is used.
+ * 
+ * The description field is not explicitly set, so will default to the link text.
+ * @type {dataTransformer}
+ */
+export function dataTransformer(pData){
+    let text = pData.title;
+    if(pData.h1s.length === 1){
+        text = pData.mainHeading;
+    }
+    return new LinkData(pData.url, text);
+}
+
+/**
+ * The collection of named link templates loaded by the Linkifier constructor. All templates strip UTM parameters from the URL, and regularise white space in the text and descriptions.
+ * @type {Object.<string, module:link-template.LinkTemplate>}
+ * @property {module:link-template.LinkTemplate} html - The default HTML link template. Uses the link title as a the text and description as the hover-text.
+ * @property {module:link-template.LinkTemplate} htmlNewTab - The same as the `html` template, but with a `target="_blank"` attribute added.
+ * @property {module:link-template.LinkTemplate} markdown - The default Markdown link template. Uses the link title as the text, and ignores the description.
+ * @see {@link module:utilities.stripUTMParameters} for the function used to strip UTM parameters from the URL.
+ * @see {@link module:utilities.regulariseWhitespace} for the function used to regularise white space in the text and description.
  */
 export const linkTemplates = {
     html: new LinkTemplate(
@@ -43,8 +67,18 @@ export const linkTemplates = {
 };
 
 /**
- * The default list of words with special capitalisations.
+ * When conbverting strings to title case, some joiner words should be preserved in all lower case. The Title Case module handles most appropriately, but not all.
+ * These are the additional words that also treated as so-called *small words* by the functions in the utility module.
+ * @type {string[]}
+ * @see {@link module:utilities.toTitleCase} for the function that uses this list to treat these words as small words by default.
+ * @see {@link module:title-case} for the Title Case module who's default small word list is augmented by this list.
+ */
+export const smallWords = [ 'is', 'its' ];
+
+/**
+ * When converting strings to title case, some words need to have their capitalisations corrected. These are the custom capitalisations that will be used by default.
  * @type {string[]}
+ * @see {@link module:utilities.toTitleCase} for the function that uses this list to correct capitalisations by default.
  */
 export const speciallyCapitalisedWords = [
     // generic acronyms
@@ -100,4 +134,4 @@ export const speciallyCapitalisedWords = [
     'DisplayPort',
     'LinkedIn',
     'ChatGPT'
-];
+];

package/src/index.js

@@ -1,16 +1,27 @@
 /**
- * @file The module's entry point. This file determines what does and does not get exported by the module.
+ * @file Defines the public interface for the published module.
  * @author Bart Busschots <opensource@bartificer.ie>
+ * @license MIT
  */
 
 /**
- * The package entry-point.
+ * The main module exposed in the npm package `@bartificer/linkify`. This module exposes the public interface, but does not implement any functionality.
  * 
+ * To understand the link generation functionality, the appropraite entry point into the code is the {@link module:linkifier.Linkifier} class.
+ * @summary The main module exposed in the npm package `@bartificer/linkify`.
  * @module linkify
- * @requires Linkifier
- * @requires LinkData
- * @requires LinkTemplate
- * @requires PageData
+ * @requires linkifier
+ * @requires link-data
+ * @requires link-template
+ * @requires page-data
+ * @see {@link module:linkifier.Linkifier} for the entry point into the link generation functionality.
+ * @example <caption>Basic Usage</caption>
+ * import { linkify } from '@bartificer/linkify';
+ * 
+ * (async () => {
+ *    console.log(await linkify.generateLink('https://github.com/bartificer'));
+ *    // Output: <a href="https://github.com/bartificer" title="Bartificer Creations · GitHub">Bartificer Creations · GitHub</a>
+ * })();
  */
 import { Linkifier } from "./Linkifier.class.mjs";
 import { LinkData } from "./LinkData.class.mjs";
@@ -21,27 +32,51 @@ import { PageData } from "./PageData.class.mjs";
 // === export the public API ===
 //
 
-/** The module's current SEMVER version number. */
+/**
+ *  The module's current SEMVER version number.
+ *  @type {string}
+ *  @see {@link https://semver.org/}
+ */
 export const VERSION = process.env.VERSION; // Webpack replaces this line with the actual version string during build
 
-/** An instantiated Linkifier object ready for use. */
+/** 
+ * An instantiated Linkifier object ready for use with the default settings as generated with the defauly constructor.
+ * @type {module:linkifier.Linkifier}
+ */
 export const linkify = new Linkifier();
 
 export {
-    /** The Linkifier class that encapsulates the link generations functionality. */
+    /**
+     * The Linkifier class that provides the core link generation functionality.
+     * @type {module:linkifier.Linkifier}
+     */
     Linkifier,
 
-    /** The PageData class used to store webpage properties like title and headings. */
+    /**
+     * The data representation class capturing the information extracted from a web page, for example the page's title and headings.
+     * @type {module:page-data.PageData}
+     */
     PageData,
 
     /**
-     * The LinkData class use to store link properties like title and url. */
+     * The data representation class capturing the information about a link, for example its title and URL.
+     * @type {module:link-data.LinkData}
+     */
     LinkData,
 
     /**
-     * The LinkTempalte class used for defining the templates for generating links. */
+     * The class capturing the details of a template used to render links.
+     * @type {module:link-template.LinkTemplate}
+     */
     LinkTemplate
 };
 
-/** The default export. */
+/**
+ * The default export, equivalent to the `linkify` named export.
+ * @name default
+ * @static
+ * @constant
+ * @type {module:linkifier.Linkifier}
+ * @see {@link module:linkify.linkify}
+ */
 export { linkify as default };

package/src/typedefs.jsdoc

@@ -0,0 +1,52 @@
+/**
+ * Functions for converting information extracted from a web page into the information used to render links.
+ * @callback dataTransformer
+ * @param {module:page-data.PageData} pData - The web page data to be transrormed to link data.
+ * @returns {module:link-data.LinkData} The link information derived from the page data.
+ */
+
+/**
+ * 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.
+ * @callback templateFieldFilterFunction
+ * @param {string} originalString - the original value for the field to be filtered.
+ * @returns {string} the filtered version of the original string.
+ */
+
+/**
+ * A tupple (array of length exactly two) for assigning a field filter to a template.
+ * @typedef {Array} templateFieldFilterTuple
+ * @property {"all"|"url"|"text"|"description"} 0 - the property the filter should be applied to.
+ * @property {templateFieldFilterFunction} 1 - the filter function to apply.
+ */
+
+/**
+ * A plain object represeting the information about about link that can get utilised in a template.
+ *
+ * Note that the `uri` could contain more fields - it's initialised with output from the `URI.parse()` function from the `URI` module.
+ * @typedef {Object} plainLinkInformationObject
+ * @property {string} url - the URL for the link.
+ * @property {string} text - the text for the link.
+ * @property {string} description - a description for the link.
+ * @property {Object} uri - the URL's components
+ * @property {string} url.hostname - the hostname part of the URL.
+ * @property {string} url.path - the path part of the UL, `/` for an empty path.
+ * @property {boolean} url.hasPath - whether or not the URL has a path, note that `/` is considered no path.
+ * @see {@link https://medialize.github.io/URI.js/docs.html#static-parse}
+ */
+
+/**
+ * A plain object representing the infomration extracted from a web page.
+ * 
+ * Note that the `uri` could contain more fields - it's initialised with output from the `URI.parse()` function from the `URI` module.
+ * @typedef {Object} plainPageInformationObject
+ * @property {string} url - the page's URL.
+ * @property {string} title - the page's title.
+ * @property {string[]} topLevelHeadings - the text from the page's `h1` tags.
+ * @property {string[]} secondaryHeadings - text from the page's `h2` tags.
+ * @property {string} mainHeading - the text from the most semantically important heading that exists in the page.
+ * @property {Object} uri - the URL's components
+ * @property {string} url.hostname - the hostname part of the URL.
+ * @property {string} url.path - the path part of the UL, `/` for an empty path.
+ * @property {boolean} url.hasPath - whether or not the URL has a path, note that `/` is considered no path.
+ * @see {@link https://medialize.github.io/URI.js/docs.html#static-parse}
+ */

package/src/utilities.mjs

@@ -1,15 +1,20 @@
 /**
  * @file A collection of useful utility functions.
  * @author Bart Busschots <opensource@bartificer.ie>
+ * @license MIT
  */
 
 /**
- * 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.
+ * 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.
+ * 
+ * This module is exposed to end-users as {@link module:linkifier.Linkifier#utilities} and {@link module:linkifier.Linkifier#util}.
  * @module utilities
- * @requires module:defaults
+ * @requires defaults
  * @requires module:urijs
  * @requires module:url-slug
  * @requires module:title-case
+ * @see {@link module:linkifier.Linkifier#utilities} for the short-cut to this module exposed on the Linkifier class.
+ * @see {@link module:linkifier.Linkifier#util} for the short-cut to this module exposed on the Linkifier class.
  */
 import * as defaults from './defaults.mjs';
 import URI from 'urijs';
@@ -20,27 +25,27 @@ import * as titleCase from 'title-case';
  * Regularise white space by replacing all sequences of whitespace characters with a single space and trimming leading and trailing whitespace.
  *
  * @param {string} text
- * @return {string}
+ * @returns {string}
  */
 export function regulariseWhitespace(text){
     return String(text).replace(/[\s\n]+/g, ' ').trim();
 };
 
 /**
- * Strip the query string from a URL.
+ * Strip the query string from a URL, if present.
  *
- * @param {string} url
- * @return {string}
+ * @param {string} url - a URL with our without a query string.
+ * @returns {string} the original URL with the query string removed, if it was present.
  */
 export function stripQueryString(url){
     return URI(url).query('').toString();
 };
 
 /**
- * Remove UTM parameters from the query string in a URL.
+ * Remove UTM parameters from the query string in a URL, if present.
  * 
- * @param {string} url
- * @return {string}
+ * @param {string} url - a URL with or without UTM parameters in the query string.
+ * @returns {string} the original URL with the UTM parameters removed, if they were present, but with any other query parameters preserved.
  * @see {@link https://en.wikipedia.org/wiki/UTM_parameters}
  */
 export function stripUTMParameters(url){
@@ -53,7 +58,7 @@ export function stripUTMParameters(url){
  * _**Note:** this is not a standard Javascript feature as of April 2026, though it is coming in future versions of Javascript._
  * 
  * @param {string} str - the string to escape.
- * @returns {string}
+ * @returns {string} the escaped string, ready for use in a regular expression.
  * @see {@link https://stackoverflow.com/a/3561711/174985}
  */
 export function escapeRegex(str) {
@@ -61,11 +66,12 @@ export function escapeRegex(str) {
 }
 
 /**
- * Batch-customise word casings in a string. E.g. force `fbi` to `FBI`, `ios` to `iOS`, etc..
+ * Batch-fix words with special capitalisations in a string. E.g. force `fbi` to `FBI`, `ios` to `iOS`, etc..
  * 
- * @param {string} str - the string to apply the replacemnts to.
- * @param {string[]} [words] - an array of words in their desired capitalisations. Defaults to the default list of custom capitalisations.
- * @returns {string}
+ * @param {string} str - the string to apply the capitalisation corrections to.
+ * @param {string[]} [words] - the list of words with special capitalisations. Defaults to the default list {@link module:defaults.speciallyCapitalisedWords}.
+ * @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.
+ * @see {@link module:defaults.speciallyCapitalisedWords} for the default list of custom capitalisations.
  */
 export function batchFixCustomWordCases(str, words){
     // coerce the first argument to a string
@@ -96,12 +102,47 @@ export function batchFixCustomWordCases(str, words){
     return ans;
 }
 
+/**
+ * Convert a string to title case, with some custom capitalisations.
+ * 
+ * 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.
+ * All words this mododule defies as being so-called *small words* (e.g., "the", "a" & "an") are preserved in lower case, as well as the additional words defined in {@link module:defaults.smallWords}.
+ * 
+ * @param {string} str - the string to convert to title case.
+ * @param {string[]} [words] - a list of words with custom capitalisations to correct after title-casing. Defaults to {@link module:defaults.speciallyCapitalisedWords}.
+ * @returns {string} the original string converted to title case, with the custom capitalisations applied.
+ * @see {@link module:defaults.speciallyCapitalisedWords} for the default list of custom capitalisations.
+ * @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.
+ * @see {@link module:defaults.smallWords} for the additional list of small words that are preserved in lower case.
+ */
+export function toTitleCase(str, words){
+    // coerce the first argument to a string
+    let ans = String(str);
+
+    // add the additional small words
+    for (const smallWord of defaults.smallWords){
+        console.log(`adding smallWord: ${smallWord}`);
+        titleCase.SMALL_WORDS.add(smallWord);
+    }
+
+    // convert to title case
+    ans = titleCase.titleCase(ans);
+
+    // fix any words with unusual customisations
+    ans = batchFixCustomWordCases(ans, words);
+
+    // return the result
+    return ans;
+}
+
 /**
  * Extract the slug from a URL and convert it to a title-case string.
  * 
- * @param {string} url
- * @param {string[]} [words] - a list of words with custom capitalisations to correct after title-casing.
- * @return {string}
+ * @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.
+ * @param {string[]} [words] - a list of words with custom capitalisations to correct after title-casing. Defaults to {@link module:defaults.speciallyCapitalisedWords}.
+ * @returns {string} the slug extracted from the URL, converted to title case, with the custom capitalisations applied.
+ * @see {@link module:defaults.speciallyCapitalisedWords} for the default list of custom capitalisations.
+ * @see {@link toTitleCase} for the function used for the title-casing.
  */
 export function extractSlug(url, words){
     // TO DO - add validation
@@ -143,7 +184,7 @@ export function extractSlug(url, words){
     title = titleCase.titleCase(title);
 
     // fix any words with unusual customisations
-    title = batchFixCustomWordCases(title, words);
+    title = toTitleCase(title, words);
 
     return title;
 };