@bartificer/linkify 2.2.0 → 2.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bartificer/linkify",
-  "version": "2.2.0",
+  "version": "2.3.2",
   "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

@@ -44,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.
          *
@@ -74,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.
      *
@@ -280,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);

package/src/defaults.mjs

@@ -2,7 +2,8 @@ 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(
@@ -29,3 +30,58 @@ export const linkTemplates = {
         ]
     )
 };
+
+/**
+ * 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',
+    'FIFA',
+    'TV',
+    'VR',
+    'BAFTA',
+    'BBC',
+    'AI',
+    'VP',
+    'II',
+    'III',
+    'IV',
+
+    // tech jargon
+    'iOS',
+    'macOS',
+    'iPhone',
+    'iPad',
+    'iPod',
+    'AirTag',
+    'iPadOS',
+    'watchOS',
+    'tvOS',
+    'CarPlay',
+    'AirPods',
+    'MacBook',
+    'iTunes',
+    'WWDC',
+    'XDR',
+    'XProtect',
+    'VESA',
+    'HDMI',
+    'DisplayPort',
+    'LinkedIn',
+    'ChatGPT'
+];

package/src/utilities.mjs

@@ -1,5 +1,7 @@
 import URI from 'urijs';
 import * as urlSlug from 'url-slug';
+import * as 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.
@@ -32,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/
@@ -50,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);
@@ -59,6 +118,18 @@ 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
+    titleCase.SMALL_WORDS.add('is');
+    title = titleCase.titleCase(title);
+
+    // fix any words with unusual customisations
+    title = batchFixCustomWordCases(title, words);
+
+    return title;
 };