The-arbiter NPM

The Arbiter

The Arbiter is a HTML routing and analytics system for front-end applications and websites. (based on ExpressJS Route handling and React-like loading - for front-end only)

The Arbiter preloads pages into memory and swaps pages into a container. This significantly decreases render time and page navigation. Custom page-specific rendering can be done in one of three states: preRender, onRender, postRender.

Installation:

npm install the-arbiter

Set up and config

Set up

If you are using gulp in conjuction with this module, place the following code in your global.js file.

function locationHashChanged( e ) {
    if( !_a.isPageRouted( location.hash ) ) return;
    if( !_a.hashToKey( location.hash ) || _a.currentPage === '' ) return;
    if( _a.isPageRendered( location.hash ) ) return;
    _a.load( location.hash, true, () => console.log( location.hash + ' loaded' ) );
    Arbiter.onLocationHashChanged( e );
}

function pageDidChange( e ) {
    locationHashChanged( e );
    Arbiter.onPageDidChange( e );
}

window.onhashchange   = locationHashChanged;
window.addEventListener( 'popstate', pageDidChange );
document.addEventListener( 'DOMContentLoaded', e => Arbiter.onApplicationDidAppear() );
window.onload         = Arbiter.onApplicationDidLoad;
window.onbeforeunload = Arbiter.onApplicationDidUnload;

Configuration

const
    _pages = {
        pagePath: 'main',
        mainFile: 'home',
        pages: [
            {
                name: 'home',
                title: 'Website | Home',
                preload: false,
                data: null,
                preRender: "console.log( 'pre' )",
                onRender: "console.log( 'on' )",
                postRender: "console.log( 'post' )"
            }
        ]
    },
    Arbiter = require( 'the-arbiter' ),
    _a = new Arbiter( _pages, true );

_a.init();

_pages is the primary variable. This can be an in-memory object, or loaded json.

Required keys for _pages

pagePath: (string) location of all your page files
mainFile: (string) your "index.html" or "primary" landing page.
pages: (array) list of all pages in application

Required fields for a Page

name: (string) the name of the file
title: (string) equivalent to <title> at the top of your pages - will set the page title
preload: (bool) tells the application to preload your file on ApplicationDidAppear

Optional fields for a Page

data (string) the raw HTML for your page
preRender (function | string) the function called before the page is loaded
onRender (function | string) the function called when the page is loaded
postRender (function | string) the function called after the page is loaded

Application Lifecycle

onApplicationDidAppear: called immediately when the application starts to load
onApplicationDidLoad: called after the DOM loads
onApplicationIsReady: called after The Arbiter finishes loading and the application is ready
onPageDidChange: called on page change (Example: back, forward, refresh)
onLocationHashChanged: called when the hyperlink hash changes (Example: #home to #login)
onApplicationDidUnload: called when the application starts to close
onApplicationDidDisappear: called just before the application closes
applicationDidReceiveMemoryWarning: called if The Monitor detects a memory issue

The Arbiter

arbiter

Manages page routing, monitoring, and lifecycle.

constructor
- Arguments:
  - (array) pages: config object including the array of pages for the arbiter to manage
  - (boolean) verbose: log the Arbiter's actions
- Sets up routes, pages, and currentPage
init
- Arguments:
  - (function) fn: function to run on initialization
  - (function) globalExecution: add globally executed function
- Gets the body container - modify this to call another div if you have a permanent navigation bar or something like that
- Constructs the pages
- Loads the mainFile and calls onApplicationIsReady
render
- Arguments:
  - (Page) page
- Calls preRender, onRender, and postRender in their respective order
- Sets currentPage
- Sets document.title and location.hash based on page object
- Sends page data to the render container
request
- Arguments:
  - (string) url
- Loads the html page - can be used to load any http page
load
- Arguments:
  - (string) name: name of the page
  - (bool) render: set render page flag
  - (function) handler: optional call back
- Renders a page if it is loaded into memory, otherwise, request's it, stores it, and then calls render
- Responses with the XMLHttpRequest on readyState 4
changePage
- Arguments:
  - (string) hash
- Primary navigation function
- Changes page location to the desired page - notifies Arbiter.onLocationHashChanged
hashToKey
- Arguments:
  - (string) hash
- Removes # in location.hash URI component and returns result
hashToKey
- Arguments:
  - (string) hash
- Adds # for location.hash URI component and returns result
isPageRouted
- Arguments:
  - (string) hash
- Returns if(?) the page is routed and managed by The Arbiter
isPageLoaded
- Arguments:
  - (string) hash
- Returns if(?) the page has been loaded into memory
isPageRendered
- Arguments:
  - (string) hash
- Returns if(?) the page is currently rendered
isPage
- Arguments:
  - (Page) page
- Returns if(?) page is an instance of Page
pageToHash
- Arguments:
  - (Page | string) page
- Returns hash of a page or string
getPage
- Arguments:
  - (Page | string) page
- Returns a Page from a hash, key, or Page
setPreRenderForPage
- Arguments:
  - (Page | string) page
  - (function) fn
- Sets the PreRender function for a specific page
setOnRenderForPage
- Arguments:
  - (Page | string) page
  - (function) fn
- Sets the OnRender function for a specific page
setPostRenderForPage
- Arguments:
  - (Page | string) page
  - (function) fn
- Sets the PostRender function for a specific page
setMainFile
- Arguments:
  - (string) page
- Sets the mainFile on in-memory configuation
- Example use: After a user logs in, set the main page from login to dashboard
addGlobalExecution
- Arguments:
  - (function) fn
- Subscribes a function to the globalExecution pubsub (see below)
invokeGlobalExecution
- Arguments:
  - (ANY) event
- Publishes anything to all subscribers of globalExecution
subscribeToPage
- Arguments:
  - (Page | string) page
  - (function) fn
- Subscribes a function to a specified Page
publishForPage
- Arguments:
  - (Page | string) page
  - (AND) event
- Publishes anything to all subscribers of a specified Page

Static Methods

onApplicationDidAppear
- Called immediately when URL for website is requested
onApplicationDidLoad
- Called when DOM/document is ready
onApplicationIsReady
- Called when The Arbiter is prepared
onPageDidChange
- Called on page history change
  - refresh, forward, backward
onLocationHashChanged
- Called when location.hash is changed
onApplicationDidUnload
- Called when the tab is set to close or the URL changes
onApplicationDidDisappear
- Called just before the application closes
- Volatile code execution will occur, not really to be used
onApplicationDidReceiveMemoryWarning
- Called if The Monitor detects a memory issue
- Clears out large in-memory objects

Important methods/variables

globalExecution
- Global Execution is a Post-Render function or multiple functions that are run globally and have no ties to a specific page.
saveOnUnload
- Attempts to save the state of the application before fully unloading
- Returns onApplicationDidDisappear - if changed to return a (string) a warning box will appear and block all code execution

The Monitor

monitor

Monitors memory, page duration, and activity.

constructor
- Arguments: none
- Sets up monitoring
analyze
- Arguments: (string) name
- Calls start and stop to handle page change requests
- Checks and reports on memory usage
onMemoryWarning
- Arguments: none
- Manual override memory warning to stop the monitor from running
inquiry
- Arguments: none
- Returns the current list of page analytics
start
- Arguments: none
- Starts a "timer" for the currently rendered page
stop
- Arguments: nothing
- Stops the "timer" for the currently rendered page
- Adds: activePage, navigatedTo, viewTime, viewDuration, memoryUsage to views object
- Saves state of The Monitor

The Generator

generator

Sets up a promisified generatorFunction to contain and manage a code execution. A contained code execution environment allows code passed in JSON to be executed without effecting other code in the window.

generator
- Arguments: (__generatorFunction__) gen
- Wraps a generator into a handled promise-like state for success and error handling
generator.container
- Arguments: (function) func
- Creates a container around a function so code execution is separate from the others
toPromise
- Arguments: (object) obj
- Coerces anything into a promise
thunkToPromise
- Arguments: (function) fn
- Sometimes you think a function returns or is a promise, but it's not. Sometimes you think it's a function but it doesn't have "arguments".
- This function takes what you thunk was a promise, calls it, and sends it back as an actual promise.
arrayToPromise
- Arguments: (array) obj
- Coerces an Array into a promise
objectToPromise
- Arguments: (object) obj
- Coerces an Object into a promise
isPromise
- Arguments: (Anything) obj
- Returns if(?) it's thenable
isGenerator
- Arguments: (Anything) obj
- Returns if(?) it's thenable and throwable because it must catch errors
isGeneratorFunction
- Arguments: (Anything) obj
- Returns if(?) an object is a generator
isObject
- Arguments: (Anything) obj
- Returns if(?) obj is a real object

The Executor

executor

Executes a string of code in a container.

constructor
- Builds a Generator
- Executes the string as code inside a container
success
- Called if things are OK
error
- Called if things aren't OK

The Librarian

librarian

// TODO: Document Librarian

Containment

containment

Containment is a simple try-catch function. Surprisingly enough, it is about 93% MORE EFFICIENT to put only ONE try catch in your code and have try-catch functions passed in... who-da-thunk?

constructor
- Arguments:
  - (object) flood
    - (function) try function to attempt
    - (function) error function in the event of an error
    - (function) finally function called regardless of the result
    - (function) result function called with the result of try
getResult
- Arguments: none
- Returns the result of a try OR calls result again
getError
- Arguments: none
- Returns the error (likely the stackTrace) of an attempted try

Example use case:

const containment = new Containment( {
    try: () => {
        const i = 123;
        return i = 321;
    },
    error: e => {
        console.error( 'error', e );
    },
    finally: () => {
        console.log( 'finally' );
    },
    result: r => {
        console.log( 'result', r );
    }
} );

PubSub

PubSub is a Publish-Subscribe class to register functions to a specific event.

constructor
- Arguments:
  - (string) name of "topic"
  - (array) subscribers List of subscribers
isFunction
- Arguments:
  - (ANY) fn
- Returns if(?) fn is a function
addSubscription
- Arguments:
  - (function) fn
- Adds function to list of subscribers
listSubscribers
- Arguments: none
- Returns the list of subscribers
publish
- Arguments:
  - (ANY) event
- Invokes all subscribed functions and passes event