@bartificer/linkify 2.0.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@bartificer/linkify",
+  "version": "2.0.0",
+  "description": "An module for converting URLs into pretty links in any format.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "build": "webpack",
+    "publish": "npm run build && npm publish"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bartificer/linkify.git"
+  },
+  "author": "Bartificer Creations Ltd. <opensource@bartificer.ie>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/bartificer/linkify/issues"
+  },
+  "homepage": "https://github.com/bartificer/linkify#readme",
+  "dependencies": {
+    "cheerio": "^1.0.0",
+    "clipboardy": "^5.3.1",
+    "mustache": "^4.2.0",
+    "node-fetch": "^3.3.2",
+    "urijs": "^1.19.10",
+    "url-slug": "^5.0.0"
+  },
+  "devDependencies": {
+    "webpack": "^5.105.4",
+    "webpack-cli": "^7.0.2"
+  }
+}

package/src/LinkData.class.mjs

@@ -0,0 +1,135 @@
+import {default as URI} from 'urijs';
+
+export class LinkData {
+    /**
+     * This constructor throws a {@link ValidationError} unless a valid URL is passed.
+     *
+     * @param {URL} 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.
+     */
+    constructor(url, text, description){
+        // TO DO - add validation
+        
+        /**
+         * The link's URL as a URI.js object.
+         *
+         * @private
+         * @type {URIObject}
+         */
+        this._uri = URI();
+        
+        /**
+         * The link text.
+         * 
+         * @private
+         * @type {string}
+         */
+        this._text = '';
+        
+        /**
+         * The link description.
+         * 
+         * @private
+         * @type {string}
+         */
+        this._description = '';
+        
+        // store the URL
+        this.url = url;
+        
+        // set the text
+        this.text = text || this.url;
+        
+        // set the description
+        this.description = description || this._text;
+    }
+
+    /**
+     * @returns {string} a URL 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}
+     */
+    get uri(){
+        return this._uri.clone();
+    }
+
+    /**
+     * @returns {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} 
+     */
+    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}
+     */
+    asPlainObject(){
+        let ans = {
+            url: this.url,
+            text: this.text,
+            description: this.description,
+            uri: URI.parse(this._uri.toString())
+        };
+        ans.uri.hasPath = ans.uri.path !== '/';
+        return ans;
+    }
+};

package/src/LinkTemplate.class.mjs

@@ -0,0 +1,125 @@
+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.
+     */
+    constructor(templateString, filters){
+        // TO DO - add validation
+        
+        /**
+         * The Moustache template string.
+         *
+         * @private
+         * @type {templateString}
+         */
+        this._templateString = '';
+        this.templateString = templateString;
+        
+        /**
+         * The filter functions to be applied to the various fields as a plain
+         * object of arrays of {@filterFunction} callbacks indexed by:
+         * * `all` - filters to be applied to all fields.
+         * * `url` - filters to be applied to just the URL.
+         * * `text` - filters to be applied just the link text.
+         * * `description` - filters to be applied just the link description.
+         *
+         * @private
+         * @type {Object.<string, filterFunction>}
+         */
+        this._filters = {
+            all: [],
+            url: [],
+            text: [],
+            description: []
+        };
+        if(Array.isArray(filters)){
+            for(let f of filters){
+                if(Array.isArray(f)){
+                    this.addFilter(...f);
+                }
+            }
+        }
+    }
+    
+    /**
+     * Get the template string.
+     *
+     * @returns {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);
+    }
+    
+    /**
+     * Add a filter to be applied to one or all fields.
+     *
+     * 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.
+     */
+    addFilter(fieldName, filterFn){
+        // make sure that args are at least plausibly valid
+        if(typeof fieldName !== 'string' || typeof filterFn !== 'function'){
+            console.warn('silently ignoring request to add filter due to invalid args');
+            return this;
+        }
+        
+        // make sure the field name is valid
+        if(!this._filters[fieldName]){
+            console.warn(`silently ignoring request to add filter for unknown field (${fieldName})`);
+            return this;
+        }
+        
+        // add the filter
+        this._filters[fieldName].push(filterFn);
+        
+        // return a reference to self
+        return this;
+    }
+    
+    /**
+     * A function 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.
+     */
+    filtersFor(fieldName){
+        fieldName = String(fieldName);
+        let ans = [];
+        
+        if(this._filters[fieldName]){
+            if(fieldName !== 'all'){
+                for(let f of this._filters.all){
+                    ans.push(f);
+                }
+            }
+            for(let f of this._filters[fieldName]){
+                ans.push(f);
+            }
+        }
+        return ans;
+    }
+};

package/src/Linkifier.class.mjs

@@ -0,0 +1,211 @@
+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 fetch from 'node-fetch';
+import * as cheerio from 'cheerio';
+import Mustache from 'mustache';
+
+export class Linkifier {
+    constructor(){
+        /**
+         * A mapping of domain names to data transformation functions.
+         *
+         * @private
+         * @type {Object.<FQDN, dataTransformer>}
+         */
+        this._pageDataToLinkDataTransmformers = {
+            '.' : function(pData){
+                let text = pData.title;
+                if(pData.h1s.length === 1){
+                    text = pData.mainHeading;
+                }
+                return new LinkData(pData.url, text);
+            }
+        };
+
+        /**
+         * The registered link templates.
+         *
+         * @private
+         * @type {Object.<templateName, module:@bartificer/linkify.LinkTemplate>}
+         */
+        this._linkTemplates = {};
+
+        /**
+         * A collection of utility functions.
+         *
+         * @private
+         * @type {Object.<string, Function>}
+         */
+        this._utilities = utilities;
+
+        //
+        // === 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}}})')
+        );
+    }
+
+    /**
+     * @type {Object.<string, Function>}
+     */
+    get utilities() {
+        return this._utilities;
+    }
+
+    /**
+     * @see Linfifier.utilities
+     */
+    get util(){
+        return this._utilities;
+    }
+
+    /**
+     * Register a data transformer function for a given domain.
+     *
+     * @param {domainName} domain - The 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
+    
+        let fqdn = String(domain);
+        if(!fqdn.match(/[.]$/)){
+            fqdn += '.';
+        }
+        this._pageDataToLinkDataTransmformers[fqdn] = transformerFn;
+    }
+
+    /**
+     * 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.
+     */
+    getTransformerForDomain(domain){
+        // TO DO - add validation
+    
+        let fqdn = String(domain);
+        if(!fqdn.match(/[.]$/)){
+            fqdn += '.';
+        }
+    
+        // return the most exact match
+        while(fqdn.match(/[.][^.]+[.]$/)){
+            if(this._pageDataToLinkDataTransmformers[fqdn]){
+                //console.log(`returning transformer for '${fqdn}'`);
+                return this._pageDataToLinkDataTransmformers[fqdn];
+            }
+            //console.log(`no transformer found for '${fqdn}'`);
+            fqdn = fqdn.replace(/^[^.]+[.]/, '');
+        }
+        //console.log('returning default transformer');
+        return this._pageDataToLinkDataTransmformers['.'];
+    }
+
+    /**
+     * 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.
+     */
+    registerTemplate(name, template){
+        // TO DO - add validation
+    
+        this._linkTemplates[name] = template;
+    }
+
+    /**
+     * 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.
+     */
+    async fetchPageData(url){
+        // TO DO - add validation
+        
+        let ans = new PageData(url);
+        
+        // then try load the contents form the web
+        let webDownloadResponseBody = '';
+        try {
+            let webDownloadResponse = await fetch(url);
+            if(!webDownloadResponse.ok){
+                throw new Error(`HTTP ${webDownloadResponse.status}: ${webDownloadResponse.statusText}`);
+            }
+            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';
+            return ans;
+        }
+        let $ = cheerio.load(webDownloadResponseBody);
+        ans.title = $('title').text().trim();
+        $('h1').each(function(){
+            ans.h1($(this).text().trim());
+        });
+        $('h2').each(function(){
+            ans.h2($(this).text().trim());
+        });
+        
+        // return the answer
+        return ans;
+    }
+
+    /**
+     * Generate a link given a URL.
+     *
+     * @async
+     * @param {URL} url
+     * @param {templateName} [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
+        
+        let tplName = templateName && typeof templateName === 'string' ? templateName : 'html';
+        
+        // get the page data        
+        let pData = await this.fetchPageData(url);
+        
+        // transform the page data to link data
+        let lData = this.getTransformerForDomain(pData.uri.hostname())(pData);
+        
+        // render the link
+        return Mustache.render(this._linkTemplates[tplName].templateString, lData.asPlainObject());
+    }
+};