@bartificer/linkify 2.1.0 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bartificer/linkify",
-  "version": "2.1.0",
+  "version": "2.3.1",
   "description": "An module for converting URLs into pretty links in any format.",
   "publishConfig": {
     "access": "public"
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "webpack",
-    "publish": "npm run build && npm publish"
+    "release": "npm run build && npm publish"
   },
   "repository": {
     "type": "git",
@@ -32,6 +32,7 @@
     "clipboardy": "^5.3.1",
     "mustache": "^4.2.0",
     "node-fetch": "^3.3.2",
+    "title-case": "^4.3.2",
     "urijs": "^1.19.10",
     "url-slug": "^5.0.0"
   },

package/src/Linkifier.class.mjs

@@ -26,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.
          *
@@ -34,6 +44,15 @@ export class Linkifier {
          */
         this._linkTemplates = {};
 
+        /**
+         * The loaded list of words with customised capitalisations.
+         * 
+         * @private
+         * @type {string[]}
+         */
+        this._speciallyCapitalisedWords = [];
+        defaults.speciallyCapitalisedWords.map(word => this._speciallyCapitalisedWords.push(word));
+
         /**
          * A collection of utility functions.
          *
@@ -50,13 +69,6 @@ export class Linkifier {
         }
     }
 
-    /**
-     * @type {string[]} A list of the names of the registered link templates.
-     */
-    get templateNames() {
-        return Object.keys(this._linkTemplates);
-    }
-
     /**
      * @type {Object.<string, Function>}
      */
@@ -71,6 +83,24 @@ export class Linkifier {
         return this._utilities;
     }
 
+    /**
+     * @returns {string[]} The current list of known words with special capitalisations.
+     */
+    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
+
+        this._speciallyCapitalisedWords = words;
+    }
+
     /**
      * Register a data transformer function for a given domain.
      *
@@ -126,6 +156,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.
      *
@@ -136,8 +199,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['.'];
     }
 
     /**
@@ -164,9 +307,8 @@ export class Linkifier {
             webDownloadResponseBody = await webDownloadResponse.text();
         } catch (err) {
             // fall back to extracting the title from the URL slug
-            console.warn(`Failed to fetch page data for '${url}': ${err.message}`);
-            console.warn('Falling back to reversing the URL slug for the title');
-            ans.title = this.utilities.extractSlug(url) || 'Untitled';
+            console.warn(`Falling back to de-slugifying URL (${err.message})`);
+            ans.title = this.utilities.extractSlug(url, this._speciallyCapitalisedWords) || 'Untitled';
             return ans;
         }
         let $ = cheerio.load(webDownloadResponseBody);
@@ -183,7 +325,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
@@ -194,16 +338,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

@@ -1,10 +1,76 @@
 import { LinkTemplate } from './LinkTemplate.class.mjs';
+import * as utilities from "./utilities.mjs";
 
 /**
- * @type {Object.<string, LinkTemplate>} A collection of named link templates.
+ * The collection of named link templates loaded by the Linkifier constructor.
+ * @type {Object.<string, LinkTemplate>}
  */
 export const linkTemplates = {
-    html: new LinkTemplate('<a href="{{{url}}}" title="{{description}}">{{text}}</a>'),
-    htmlNewTab: new LinkTemplate('<a href="{{{url}}}" title="{{description}}" target="_blank" rel="noopener">{{text}}</a>'),
-    markdown: new LinkTemplate('[{{{text}}}]({{{url}}})')
+    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]
+        ]
+    )
 };
+
+/**
+ * The default list of words with special capitalisations.
+ * @type {string[]}
+ */
+export const speciallyCapitalisedWords = [
+    // generic acronyms
+    'FBI',
+    'CIA',
+    'USA',
+    'UK',
+    'EU',
+    'NASA',
+    'NSA',
+    'OS',
+    'OSes',
+    'ID',
+    'IDs',
+    'MLB',
+    'NFL',
+    'NASCAR',
+    'TV',
+    'VR',
+    'BAFTA',
+    'BBC',
+    'AI',
+    'VP',
+
+    // tech jargon
+    'iOS',
+    'macOS',
+    'iPad',
+    'iPod',
+    'iPadOS',
+    'watchOS',
+    'tvOS',
+    'CarPlay',
+    'AirPods',
+    'MacBook',
+    'iTunes',
+    'XProtect',
+    'LinkedIn',
+    'ChatGPT'
+];

package/src/utilities.mjs

@@ -1,5 +1,17 @@
 import URI from 'urijs';
 import * as urlSlug from 'url-slug';
+import { titleCase } from "title-case";
+import * as defaults from './defaults.mjs';
+
+/**
+ * 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.
@@ -22,13 +34,69 @@ export function stripUTMParameters(url){
     return URI(url).removeQuery(['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content']).toString();
 };
 
+/**
+ * Escape a string for use in regular expressions.
+ * 
+ * @param {string} str - the string to escape.
+ * @returns {string}
+ * @note much to my surprise, not a standard Javascript feature!
+ * @see https://stackoverflow.com/a/3561711/174985
+ */
+export function escapeRegex(str) {
+    return String(str).replace(/[/\-\\^$*+?.()|[\]{}]/g, '\\$&');
+}
+
+/**
+ * Batch-customise word casings 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}
+ */
+export function batchFixCustomWordCases(str, words){
+    // coerce the first argument to a string
+    let ans = String(str);
+
+    // resolve the word list
+    if(arguments.length < 2){
+        // if none was passed, use the default list
+        words = defaults.speciallyCapitalisedWords;
+    } else {
+        // TO DO — add validation
+    }
+
+    // build a mapping from the lower-case version of each word to custom version
+    const lowerToCustomMap = {};
+    words.map(word => lowerToCustomMap[word.toLowerCase()] = word);
+
+    // assemble an RE from all the words
+    const sortedWords = Object.keys(lowerToCustomMap).sort((a, b) => b.length - a.length); // sort for efficiency
+    const wordRE = new RegExp(
+        sortedWords.map(word => `\\b${escapeRegex(word)}\\b`).join('|'),
+        'gi'
+    );
+
+    // replace all the matches at once using an anonymous function as the replacement
+    ans = str.replace(wordRE, match => lowerToCustomMap[match.toLowerCase()]);
+
+    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}
  */
-export function extractSlug(url){
+export function extractSlug(url, words){
+    // TO DO - add validation
+
+    // resolve the list of words with custom capitalisations
+    if(arguments.length < 2){
+        words = [];
+    }
+
     // example URLs to try support:
     // ----------------------------
     // https://www.macobserver.com/news/apple-q2-2026-earnings-call-date-confirmed-heres-what-to-expect/
@@ -40,7 +108,8 @@ export function extractSlug(url){
     // 2. Trim leading and trailing slashes
     // 3. Split the path on / into segments and take the last segment.
     // 4. Remove any file extension.
-    // 5. Call slug reversing function with Title Case option.
+    // 5. Call slug reversing function with the lower-case option.
+    // 6. Intelligently Title-case the title.
 
     // extract the path from the URL and clean up both ends
     const uri = URI(url);
@@ -49,6 +118,17 @@ export function extractSlug(url){
     let slug = path.split('/').pop() || ''; // get last segment of the path
     slug = slug.replace(/\.[^/.]+$/, ''); // trim any file extension that might be present
     
-    // reverse the slug into a title-case string
-    return urlSlug.revert(slug, { transformer: urlSlug.TITLECASE_TRANSFORMER });
+    // reverse the slug into a lower-case string
+    let title = urlSlug.revert(slug, { 
+        transformer: urlSlug.LOWERCASE_TRANSFORMER,
+        camelCase: false
+    });
+
+    // convert the title to title case
+    title = titleCase(title);
+
+    // fix any words with unusual customisations
+    title = batchFixCustomWordCases(title, words);
+
+    return title;
 };