@bartificer/linkify 2.0.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bartificer/linkify",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "An module for converting URLs into pretty links in any format.",
   "publishConfig": {
     "access": "public"

package/src/Linkifier.class.mjs

@@ -2,6 +2,7 @@ import { PageData } from './PageData.class.mjs';
 import { LinkData } from './LinkData.class.mjs';
 import { LinkTemplate } from './LinkTemplate.class.mjs';
 import * as utilities from "./utilities.mjs";
+import * as defaults from "./defaults.mjs";
 
 import fetch from 'node-fetch';
 import * as cheerio from 'cheerio';
@@ -25,6 +26,16 @@ export class Linkifier {
             }
         };
 
+        /**
+         * A mapping of domains names to default template names.
+         * 
+         * @private
+         * @type {Object.<FQDN, templateName>}
+         */
+        this._pageDataToLinkTemplateName = {
+            '.' : 'html' // default to the 'html' template for all domains unless otherwise specified
+        };
+
         /**
          * The registered link templates.
          *
@@ -42,21 +53,11 @@ export class Linkifier {
         this._utilities = utilities;
 
         //
-        // === Create and register the default templates ===
+        // -- Create and register the default templates --
         //
-        // TO DO — migrate these to a separate file
-        this.registerTemplate(
-            'html',
-            new LinkTemplate('<a href="{{{url}}}" title="{{description}}">{{text}}</a>')
-        );
-        this.registerTemplate(
-            'htmlNewTab',
-            new LinkTemplate('<a href="{{{url}}}" title="{{description}}" target="_blank" rel="noopener">{{text}}</a>')
-        );
-        this.registerTemplate(
-            'markdown',
-            new LinkTemplate('[{{{text}}}]({{{url}}})')
-        );
+        for (const [name, template] of Object.entries(defaults.linkTemplates)) {
+            this.registerTemplate(name, template);
+        }
     }
 
     /**
@@ -128,6 +129,39 @@ export class Linkifier {
         return this._pageDataToLinkDataTransmformers['.'];
     }
 
+    /**
+     * @type {string[]} A list of the names of the registered link templates.
+     */
+    get templateNames() {
+        return Object.keys(this._linkTemplates);
+    }
+
+    /**
+     * @returns {string} The name of the default 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]){
+            throw new ValidationError(`No template named '${tplName}' is registered`);
+        }
+        this._pageDataToLinkTemplateName['.'] = tplName;
+    }
+    
+    /**
+     * @type {LinkTemplate} The default link template.
+     */
+    get defaultTemplate(){
+        return this._linkTemplates[this._pageDataToLinkTemplateName['.']];
+    }
+
     /**
      * Register a link template.
      *
@@ -138,8 +172,88 @@ export class Linkifier {
      */
     registerTemplate(name, template){
         // TO DO - add validation
+        const tplName = String(name);
     
-        this._linkTemplates[name] = template;
+        this._linkTemplates[tplName] = template;
+    }
+
+    /**
+     * Get a registered link template by name.
+     *
+     * @param {string} templateName
+     * @returns {LinkTemplate}
+     * @throws {ValidationError} A validation error is thrown unless a valid name is passed and corresponds to a registered template.
+     */
+    getTemplate(templateName){
+        const tplName = String(templateName);
+
+        if(!this._linkTemplates[tplName]){
+            throw new ValidationError(`No template named '${tplName}' is registered`);
+        }
+        return this._linkTemplates[tplName];
+    }
+
+    /**
+     * 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.
+     */
+    registerDefaultTemplateMapping(domain, templateName){
+        // TO DO - add validation
+    
+        let fqdn = String(domain);
+        if(!fqdn.match(/[.]$/)){
+            fqdn += '.';
+        }
+        this._pageDataToLinkTemplateName[fqdn] = templateName;
+    }
+
+    /**
+     * 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
+     * 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
+     * return the default transformer.
+     *
+     * @param {domainName} domain - The domain 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
+    
+        let fqdn = String(domain);
+        if(!fqdn.match(/[.]$/)){
+            fqdn += '.';
+        }
+    
+        // return the most exact match
+        while(fqdn.match(/[.][^.]+[.]$/)){
+            if(this._pageDataToLinkTemplateName[fqdn]){
+                let tplName = this._pageDataToLinkTemplateName[fqdn];
+
+                // make sure the template exists
+                if(!this._linkTemplates[tplName]){
+                    console.warn(`No template named '${tplName}' is registered, falling back to global default '${this._pageDataToLinkTemplateName['.']}'`);
+                    return this._pageDataToLinkTemplateName['.'];
+                }
+
+                //console.log(`returning template name for '${fqdn}'`);
+                return this._pageDataToLinkTemplateName[fqdn];
+            }
+            //console.log(`no template name found for '${fqdn}'`);
+            fqdn = fqdn.replace(/^[^.]+[.]/, '');
+        }
+        //console.log('returning default template name');
+        return this._pageDataToLinkTemplateName['.'];
     }
 
     /**
@@ -185,7 +299,9 @@ export class Linkifier {
     }
 
     /**
-     * Generate a link given a URL.
+     * Generate a link given a URL. By default the registered template for the
+     * URL's domain will be used, or, if none is registered, the overall
+     * default will be used (`html`).
      *
      * @async
      * @param {URL} url
@@ -196,16 +312,52 @@ export class Linkifier {
      */
     async generateLink(url, templateName){
         // TO DO - add validation
-        
-        let tplName = templateName && typeof templateName === 'string' ? templateName : 'html';
+
+        //
+        // -- resolve the template name to use for this URL --
+        //
+        let tplName = '';
+
+        // resolve the template — if a template name is passed, try use it,
+        // otherwise resolve the default for this URL's domain
+        if(templateName && typeof templateName === 'string'){
+            tplName = templateName;
+
+            // make sure the template exists
+            if(!this._linkTemplates[tplName]){
+                console.warn(`No template named '${tplName}' is registered, falling back to global default '${this._pageDataToLinkTemplateName['.']}'`);
+                tplName = this._pageDataToLinkTemplateName['.'];
+            }
+        } else {
+            tplName = this.getTemplateNameForDomain((new URL(url)).hostname);
+        }
+        const template = this._linkTemplates[tplName];
         
         // get the page data        
-        let pData = await this.fetchPageData(url);
+        const pageData = await this.fetchPageData(url);
         
         // transform the page data to link data
-        let lData = this.getTransformerForDomain(pData.uri.hostname())(pData);
+        const linkData = this.getTransformerForDomain(pageData.uri.hostname())(pageData);
+
+        // apply field-specific filters to the link data
+        const fieldNames = ['url', 'text', 'description'];
+        const templateData = linkData.asPlainObject();
+        for(let fieldName of fieldNames){
+            let fieldFilters = template.filtersFor(fieldName);
+            for(let filterFn of fieldFilters){
+                templateData[fieldName] = filterFn(templateData[fieldName]);
+            }
+        }
+
+        // apply the universal filters to all the link data fields
+        let globalFilters = template.filtersFor('all');
+        for(let filterFn of globalFilters){
+            for(let fieldName of fieldNames){
+                templateData[fieldName] = filterFn(templateData[fieldName]);
+            }
+        }
         
         // render the link
-        return Mustache.render(this._linkTemplates[tplName].templateString, lData.asPlainObject());
+        return Mustache.render(this._linkTemplates[tplName].templateString, templateData);
     }
 };

package/src/defaults.mjs

@@ -0,0 +1,31 @@
+import { LinkTemplate } from './LinkTemplate.class.mjs';
+import * as utilities from "./utilities.mjs";
+
+/**
+ * @type {Object.<string, LinkTemplate>} A collection of named link templates.
+ */
+export const linkTemplates = {
+    html: new LinkTemplate(
+        '<a href="{{{url}}}" title="{{description}}">{{text}}</a>',
+        [
+            ['url', utilities.stripUTMParameters],
+            ['text', utilities.regulariseWhitespace],
+            ['description', utilities.regulariseWhitespace]
+        ]
+    ),
+    htmlNewTab: new LinkTemplate(
+        '<a href="{{{url}}}" title="{{description}}" target="_blank" rel="noopener">{{text}}</a>',
+        [
+            ['url', utilities.stripUTMParameters],
+            ['text', utilities.regulariseWhitespace],
+            ['description', utilities.regulariseWhitespace]
+        ]
+    ),
+    markdown: new LinkTemplate(
+        '[{{{text}}}]({{{url}}})',
+        [
+            ['url', utilities.stripUTMParameters],
+            ['text', utilities.regulariseWhitespace]
+        ]
+    )
+};

package/src/utilities.mjs

@@ -1,6 +1,16 @@
 import URI from 'urijs';
 import * as urlSlug from 'url-slug';
 
+/**
+ * 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}
+ */
+export function regulariseWhitespace(text){
+    return String(text).replace(/[\s\n]+/g, ' ').trim();
+};
+
 /**
  * Strip the query string from a URL.
  *