@bartificer/linkify 2.4.0 → 2.4.1

package/src/Linkifier.class.mjs

@@ -28,28 +28,26 @@ import Mustache from 'mustache';
  * The class providing the link rendering functionality. Instances of this class capture the settings for generating links, and, generate links using these settings.
  */
 export class Linkifier {
+    /**
+     * Builds a Linkifier instance ready for use rendering links using the default configration.
+     * @see {@link module:defaults} for the default configuration settings.
+     */
     constructor(){
         /**
-         * A mapping of domain names to data transformation functions.
+         * A mapping of fully qualified domain names to data transformation functions.
          *
          * @private
-         * @type {Object.<FQDN, dataTransformer>}
+         * @type {Object.<string, dataTransformer>}
          */
         this._pageDataToLinkDataTransmformers = {
-            '.' : function(pData){
-                let text = pData.title;
-                if(pData.h1s.length === 1){
-                    text = pData.mainHeading;
-                }
-                return new LinkData(pData.url, text);
-            }
+            '.' : defaults.dataTransformer
         };
 
         /**
-         * A mapping of domains names to default template names.
+         * A mapping of fully qualified domain names to default template names.
          * 
          * @private
-         * @type {Object.<FQDN, templateName>}
+         * @type {Object.<string, string>}
          */
         this._pageDataToLinkTemplateName = {
             '.' : 'html' // default to the 'html' template for all domains unless otherwise specified
@@ -59,7 +57,7 @@ export class Linkifier {
          * The registered link templates.
          *
          * @private
-         * @type {Object.<templateName, module:@bartificer/linkify.LinkTemplate>}
+         * @type {Object.<string, module:link-template.LinkTemplate>}
          */
         this._linkTemplates = {};
 
@@ -90,30 +88,30 @@ export class Linkifier {
 
     /**
      * @type {Object.<string, Function>}
+     * @readonly
+     * @see {@link module:utilities} for the utility functions available in this collection.
      */
     get utilities() {
         return this._utilities;
     }
 
     /**
-     * @see Linfifier.utilities
+     * Shorthand property for `.utilities`.
+     * @see {@link module:linkifier.Linkifier#utilities}
      */
     get util(){
         return this._utilities;
     }
 
     /**
-     * @returns {string[]} The current list of known words with special capitalisations.
+     * The list of known words with special capitalisations. The words should be capitalised in the descired manner.
+     * @type {string[]}
      */
     get speciallyCapitalisedWords(){
         const ans = [];
         this._speciallyCapitalisedWords.map(word => ans.push(word));
         return ans;
     }
-
-    /**
-     * @param {string[]} words - a list of words with special capitalisations
-     */
     set speciallyCapitalisedWords(words){
         // TO DO - add validation
 
@@ -121,13 +119,11 @@ export class Linkifier {
     }
 
     /**
-     * Register a data transformer function for a given domain.
+     * Register a data transformer function to a domain name.
      *
-     * @param {domainName} domain - The domain for which this transformer should be
+     * @param {string} domain - The fully qualified domain for which this transformer should be
      * used.
      * @param {dataTransformer} transformerFn - The data transformer callback.
-     * @throws {ValidationError} A validation error is thrown if either parameter
-     * is missing or invalid.
      */
     registerTransformer(domain, transformerFn){
         // TO DO - add validation
@@ -143,16 +139,14 @@ export class Linkifier {
      * Get the data transformer function for a given domain.
      *
      * Note that domains are searched from the subdomain up. For example, if passed
-     * the domain `www.bartificer.net` the function will first look for a
-     * transformer for the domain `www.bartificer.net`, if there's no transformer
+     * the domain `www.bartificer.ie` the function will first look for a
+     * transformer for the domain `www.bartificer.ie`, if there's no transformer
      * registered for that domain it will look for a transformer for the domain
-     * `bartificer.net`, if there's no transformer for that domain either it will
+     * `bartificer.ie`, if there's no transformer for that domain either it will
      * return the default transformer.
      *
-     * @param {domainName} domain - The domain to get the data transformer for.
+     * @param {string} domain - The fully qualified domain for which to get the data transformer.
      * @returns {dataTransformer}
-     * @throws {ValidationError} A validation error is thrown unless a valid domain
-     * name is passed.
      */
     getTransformerForDomain(domain){
         // TO DO - add validation
@@ -178,22 +172,20 @@ export class Linkifier {
     /**
      * A list of the names of the registered link templates.
      * @type {string[]}
+     * @readonly
      */
     get templateNames() {
         return Object.keys(this._linkTemplates);
     }
 
     /**
-     * @returns {string} The name of the default template.
+     * The name of the default template used when rendering links.
+     * @type {string}
+     * @throws {ValidationError} A validation error is thrown if the template name is missing, invalid, or doesn't correspond to a registered template.
      */
     get defaultTemplateName(){
         return this._pageDataToLinkTemplateName['.'];
     }
-
-    /**
-     * @param {string} templateName - The name of the default template to use.
-     * @throws {ValidationError} A validation error is thrown if the template name is missing, invalid, or doesn't correspond to a registered template.
-     */
     set defaultTemplateName(templateName){
         const tplName = String(templateName);
         if(!this._linkTemplates[tplName]){
@@ -204,7 +196,8 @@ export class Linkifier {
     
     /**
      * The default link template.
-     * @type {module:LinkTemplate.class.LinkTemplate}
+     * @type {module:link-template.LinkTemplate}
+     * @readonly
      */
     get defaultTemplate(){
         return this._linkTemplates[this._pageDataToLinkTemplateName['.']];
@@ -214,9 +207,7 @@ export class Linkifier {
      * Register a link template.
      *
      * @param {string} name
-     * @param {LinkTemplate} template
-     * @throws {ValidationError} A validation error is thrown unless both a valid
-     * name and template object are passed.
+     * @param {module:link-template.LinkTemplate} template
      */
     registerTemplate(name, template){
         // TO DO - add validation
@@ -229,7 +220,7 @@ export class Linkifier {
      * Get a registered link template by name.
      *
      * @param {string} templateName
-     * @returns {LinkTemplate}
+     * @returns {module:link-template.LinkTemplate}
      * @throws {ValidationError} A validation error is thrown unless a valid name is passed and corresponds to a registered template.
      */
     getTemplate(templateName){
@@ -245,10 +236,8 @@ export class Linkifier {
      * Register a default template for use with a given domain. This template will
      * override the overall default for this domain and all its subdomains.
      *
-     * @param {domainName} domain - The domain for which this template should be used by default.
-     * @param {templateName} templateName - The name of the template to use.
-     * @throws {ValidationError} A validation error is thrown if either parameter
-     * is missing or invalid.
+     * @param {string} domain - The fully qualified domain name for which this template should be used by default.
+     * @param {string} templateName - The name of the template to use.
      */
     registerDefaultTemplateMapping(domain, templateName){
         // TO DO - add validation
@@ -264,16 +253,14 @@ export class Linkifier {
      * Get the data transformer function for a given domain.
      *
      * Note that domains are searched from the subdomain up. For example, if passed
-     * the domain `www.bartificer.net` the function will first look for a
-     * transformer for the domain `www.bartificer.net`, if there's no transformer
+     * the domain `www.bartificer.ie` the function will first look for a
+     * transformer for the domain `www.bartificer.ie`, if there's no transformer
      * registered for that domain it will look for a transformer for the domain
-     * `bartificer.net`, if there's no transformer for that domain either it will
+     * `bartificer.ie`, if there's no transformer for that domain either it will
      * return the default transformer.
      *
-     * @param {domainName} domain - The domain to get the data transformer for.
+     * @param {string} domain - The fully qualified domain name to get the data transformer for.
      * @returns {dataTransformer}
-     * @throws {ValidationError} A validation error is thrown unless a valid domain
-     * name is passed.
      */
     getTemplateNameForDomain(domain){
         // TO DO - add validation
@@ -308,10 +295,8 @@ export class Linkifier {
      * Fetch the page data for a given URL.
      *
      * @async
-     * @param {URL} url
-     * @returns {PageData}
-     * @throws {ValidationError} A validation error is thrown unless a valid URL is
-     * passed.
+     * @param {string} url
+     * @returns {module:page-data.PageData}
      */
     async fetchPageData(url){
         // TO DO - add validation
@@ -351,11 +336,9 @@ export class Linkifier {
      * default will be used (`html`).
      *
      * @async
-     * @param {URL} url
-     * @param {templateName} [templateName='html']
+     * @param {string} url
+     * @param {string} [templateName='html']
      * @returns {string}
-     * @throws {ValidationError} A validation error is thrown unless a valid URL is
-     * passed.
      */
     async generateLink(url, templateName){
         // TO DO - add validation

package/src/PageData.class.mjs

@@ -1,26 +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.
+ * 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
@@ -29,7 +28,7 @@ export class PageData {
          * The page's URL as a URI object.
          *
          * @private
-         * @type {URIObject}
+         * @type {module:urijs}
          */
         this._uri = URI();
         
@@ -46,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 = {
@@ -131,8 +129,8 @@ export class PageData {
     
     /**
      * The page's top-level headings (`h1` tags).
-     *
-     * @returns {string[]}
+     * @type {string[]}
+     * @readonly
      */
     get topLevelHeadings(){
         var ans = [];
@@ -144,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;
@@ -152,8 +151,8 @@ export class PageData {
 
     /**
      * The page's secondary headings (`h2` tags).
-     *
-     * @returns {string[]}
+     * @type {string[]}
+     * @readonly
      */
     get secondaryHeadings(){
         var ans = [];
@@ -165,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;
     }
@@ -176,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){
@@ -193,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){
@@ -206,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){
@@ -216,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 = {
@@ -254,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

@@ -15,6 +15,22 @@
 import { LinkTemplate } from './LinkTemplate.class.mjs';
 import * as utilities from "./utilities.mjs";
 
+/**
+ * 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>}

package/src/index.js

@@ -14,7 +14,7 @@
  * @requires link-data
  * @requires link-template
  * @requires page-data
- * @see {@link module:linkifier.Linkifier}
+ * @see {@link module:linkifier.Linkifier} for the entry point into the link generation functionality.
  * @example <caption>Basic Usage</caption>
  * import { linkify } from '@bartificer/linkify';
  * 

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}
+ */