@bartificer/linkify 2.3.5 → 2.4.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bartificer/linkify",
-  "version": "2.3.5",
-  "description": "An module for converting URLs into pretty links in any format.",
+  "version": "2.4.1",
+  "description": "A module for converting URLs into pretty links in any format.",
   "publishConfig": {
     "access": "public"
   },
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "build": "webpack",
-    "docs": "rm -rf ./docs/* && npx jsdoc -c ./jsdoc.conf.json --destination ./docs",
+    "docs": "rm -rf ./docs/* && npx jsdoc -c ./jsdoc.conf.json",
     "release": "npm run build && npm run docs && npm login && npm publish"
   },
   "repository": {
@@ -41,7 +41,9 @@
   },
   "devDependencies": {
     "clean-jsdoc-theme": "^4.3.0",
+    "docdash": "^2.0.2",
     "jsdoc": "^4.0.5",
+    "marked": "^18.0.0",
     "webpack": "^5.105.4",
     "webpack-cli": "^7.0.2"
   }

package/src/LinkData.class.mjs

@@ -1,28 +1,28 @@
 /**
- * @file The definition of the class representing a link.
+ * @file Data model for link information.
  * @author Bart Busschots <opensource@bartificer.ie>
+ * @license MIT
  */
 
 /**
- * This module provides as class for representing the information that can be used when rendering a link.
- * @module LinkData
+ * This module provides the class for representing the information that can be used to render a link.
+ * @module link-data
  * @requires module:urijs
  */
 import {default as URI} from 'urijs';
 
 /**
- * A class for representing the information about a link, in the abstract.
+ * The information that can be used to render a link.
+ * 
+ * Instances of this class are created from the information extracted from web pages by data transformers.
+ * @see {@link dataTransformer} for details of how instances of this class are created.
  */
 export class LinkData {
     /**
-     * This constructor throws a {@link ValidationError} unless a valid URL is passed.
-     *
-     * @param {URL} url - The link's URL.
+     * @param {string} url - The link's URL.
      * @param {string} [text] - The link's text, defaults to the URL.
-     * @param {string} [description] - A description for the link, defaults to
-     * the link text.
-     * @throws {ValidationError} A validation error is thrown if an invalid URL
-     * is passed.
+     * @param {string} [description] - A description for the link, defaults to the link text.
+     * @throws {TypeError} A TypeError is thrown if an invalid URL is passed.
      */
     constructor(url, text, description){
         // TO DO - add validation
@@ -31,9 +31,9 @@ export class LinkData {
          * The link's URL as a URI.js object.
          *
          * @private
-         * @type {URIObject}
+         * @type {module:urijs}
          */
-        this._uri = URI();
+        this._uri = URI(); // throws a TypeError if the URL is invalid
         
         /**
          * The link text.
@@ -62,78 +62,50 @@ export class LinkData {
     }
 
     /**
-     * @returns {string} a URL string 
+     * The URL the link points to as a string.
+     * @type {string}
      */
     get url(){
         return this._uri.toString();
     }
-    
-    /**
-     * Get or set the URL.
-     *
-     * @param {string} url - A new URL as a string.
-     */
     set url(url){
         this._uri = URI(String(url)).normalize();
     }
     
     /**
-     * Get the URL as a URI.js object.
-     * 
-     * @returns {Object}
+     * The URL the link points to as a URI.js object representing the URL.
+     * @type {module:urijs}
+     * @readonly
      */
     get uri(){
         return this._uri.clone();
     }
 
     /**
-     * @returns {string}
+     * The link text.
+     * @type {string}
      */
     get text(){
         return this._text;
     }
-    
-    /**
-     * @param {string} [text] - New link text. The value will be coerced to a string and trimmed.
-     */
     set text(text){
         this._text = String(text).trim();
     }
     
     /**
-     * @returns {string} 
+     * The link description.
+     * @type {string}
      */
     get description(){
         return this._description;
     }
-
-    /**
-     * @param {string} description
-     */
     set description(description){
         this._description = String(description);
     }
     
     /**
-     * Get the link data as a plain object of the form:
-     * ```
-     * {
-     *     url: 'http://www.bartificer.net/',
-     *     text: 'the link text',
-     *     description: 'the link description',
-     *     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 {plainObject}
-     * @see {@link https://medialize.github.io/URI.js/docs.html#static-parse}
+     * The link data as a plain object for use in Mustache templates and the like.
+     * @returns {plainLinkInformationObject} A plain object containing the link data.
      */
     asPlainObject(){
         let ans = {

package/src/LinkTemplate.class.mjs

@@ -1,27 +1,31 @@
 /**
- * @file The definition of the class representing a link generation template.
+ * @file Link generation templates.
  * @author Bart Busschots <opensource@bartificer.ie>
+ * @license MIT
  */
 
 /**
- * This module provides as class for representing a template used for generating links.
- * @module LinkTemplate
+ * This module provides as class for representing the templates used to generate links from link data objects.
+ * @module link-template
  * @requires module:urijs
  */
 
 /**
- * A class representing the a template that can be used to render links.
+ * A class representing the templates used to render link data objects as actual links.
+ * @see {@link module:link-data.LinkData} for the data objects that are rendered with these templates.
  */
 export class LinkTemplate{
     /**
      * @param {string} templateString - A Moustache template string.
-     * @param {Array} [filters=[]] - An optional array of filter functions.
-     * Each element in the array should itself be an array where the first
-     * element is a string specifying which fields the filter should be applied
-     * to (one of `'all'`, `'url'`, `'text'`, or `'description'`), and the 
-     * second the filter function itself which should be a function that takes
-     * a single string as an argument and returns a filtered version of that
-     * string.
+     * @param {templateFieldFilterTuple[]} [filters=[]] - an optional set of filter functions to apply to some or all template fields.
+     * @example <caption>Example of defining a template with filters</caption>
+     * let template = new LinkTemplate(
+     *     '<a href="{{{url}}}">{{{text}}}</a>',
+     *     [
+     *         ['url', linkify.util.stripUTMParameters],
+     *         ['text', linkify.util.regulariseWhitespace]
+     *     ]
+     * );
      */
     constructor(templateString, filters){
         // TO DO - add validation
@@ -44,7 +48,7 @@ export class LinkTemplate{
          * * `description` - filters to be applied just the link description.
          *
          * @private
-         * @type {Object.<string, filterFunction>}
+         * @type {Object.<"all"|"url"|"text"|"description", templateFieldFilterFunction>}
          */
         this._filters = {
             all: [],
@@ -62,20 +66,12 @@ export class LinkTemplate{
     }
     
     /**
-     * Get the template string.
-     *
-     * @returns {string}
+     * The Mustache template string. Will be coerced to a string with `String(templateString)`.
+     * @type {string}
      */
     get templateString(){
         return this._templateString;
     }
-
-    /**
-     * Set the template string. Should be in Mustache format. All values passed
-     * will be coerced to strings.
-     * 
-     * @param {string} templateString
-     */
     set templateString(templateString){
         this._templateString = String(templateString);
     }
@@ -86,10 +82,9 @@ export class LinkTemplate{
      * If an invalid args are passed, the function does not save the filter or
      * throw an error, but it does log a warning.
      *
-     * @param {string} fieldName - One of `'all'`, `'url'`, `'text'`, or
-     * `'description'`.
-     * @param {function} filterFn - the filter function.
-     * @returns {LinkTemplate} Returns a reference to self to facilitate function chaining.
+     * @param {"all"|"url"|"text"|"description"} fieldName
+     * @param {templateFieldFilterFunction} filterFn - the filter function.
+     * @returns {module:link-template.LinkTemplate} Returns a reference to self to facilitate function chaining.
      */
     addFilter(fieldName, filterFn){
         // make sure that args are at least plausibly valid
@@ -112,13 +107,11 @@ export class LinkTemplate{
     }
     
     /**
-     * A function get the filter functions that should be applied to any given
-     * field.
+     * Get the filter functions that should be applied to any given field.
      * 
-     * @param {string} fieldName - one of `'url'`, `'text'`, or
-     * `'description'`.
-     * @returns {function[]} returns an array of callbacks, which may be
-     * empty. An empty array is returned if an invalid field name is passed.
+     * @param {"all"|"url"|"text"|"description"} fieldName
+     * @returns {templateFieldFilterFunction[]} returns an array of callbacks, which may be
+     * empty. An empty array is also returned if an invalid field name is passed.
      */
     filtersFor(fieldName){
         fieldName = String(fieldName);

package/src/Linkifier.class.mjs

@@ -1,14 +1,15 @@
 /**
  * @file The definition of the main Linkifier class which provides the link rendering functionality with the help of the other classes and modules.
  * @author Bart Busschots <opensource@bartificer.ie>
+ * @license MIT
  */
 
 /**
  * Linkifier's core link rendering functionality.
- * @module Linkifier
- * @requires LinkData
- * @requires LinkTemplate
- * @requires PageData
+ * @module linkifier
+ * @requires link-data
+ * @requires link-template
+ * @requires page-data
  * @requires module:node-fetch
  * @requires module:cheerio
  * @requires module:mustache
@@ -27,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
@@ -58,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 = {};
 
@@ -89,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
 
@@ -120,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
@@ -142,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
@@ -177,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]){
@@ -203,7 +196,8 @@ export class Linkifier {
     
     /**
      * The default link template.
-     * @type {LinkTemplate}
+     * @type {module:link-template.LinkTemplate}
+     * @readonly
      */
     get defaultTemplate(){
         return this._linkTemplates[this._pageDataToLinkTemplateName['.']];
@@ -212,10 +206,8 @@ export class Linkifier {
     /**
      * Register a link template.
      *
-     * @param {templateName} name
-     * @param {module:@bartificer/linkify.LinkTemplate} template
-     * @throws {ValidationError} A validation error is thrown unless both a valid
-     * name and template object are passed.
+     * @param {string} name
+     * @param {module:link-template.LinkTemplate} template
      */
     registerTemplate(name, template){
         // TO DO - add validation
@@ -228,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){
@@ -244,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
@@ -263,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
@@ -307,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
@@ -350,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