README

taproot

What is taproot

taproot is a framework in the truest sense of the word.

taproot provides everything you need to get an application with sound architectural principles running, but doesn't provide any of the parts of that application.

Imagine that your application is a house you'd like to build; taproot pours the foundation and builds scaffolding. You bring the rest.

Docs

For now, see Quick Start below

Quick Start

Installation

npm install -E @thomasrandolph/taproot

taproot ships native ES modules using bare module specifiers. If you don't already have a process that supports resolving bare module specifiers, you may want to read the Advanced Installation section.

Alternatively, see the Setup section for examples that use a version hosted by Skypack.

Setup

taproot works in a minimal mode with zero configuration.

<html>
    <head>
        <script type="module">
            import { setup } from "https://cdn.skypack.dev/@thomasrandolph/taproot";

            async function start(){
                await setup();
            }

            start();
        </script>
    </head>
</html>

By default taproot attaches itself to the global scope as window.taproot.
This is obviously undesireable in most cases, so a namespace can be provided.

await setup( {
    "namespace": "MyApp"
} );

Now your application runtime is accessible from window.MyApp.
In either case, taproot assigns your namespace to window.NAMESPACE, so it never needs to be hard-coded anywhere else.

console.log( window[ window.NAMESPACE ].startupOptions );

If you run the above code, you'll notice that db is false, but routing is true.
By default, taproot assumes that your application will have multiple routes.

For now, we can turn routing off to simplify our application.

await setup( {
    "namespace": "MyApp",
    "routing": false
} );

Now your application exists, but none of the useful features are available!
This is like pouring the foundation, but not setting up the scaffolding.

You might want to wait until you've completed other tasks before you start your application, so by default taproot is idle.
To start an idle taproot instance, you call .start().

var MyApp = await setup( {
    "namespace": "MyApp",
    "routing": false
} );

MyApp.start();

To see the event-driven power of taproot in action, let's subscribe to an event and then start the application.

async function start(){
    var MyApp = await setup( {
        "namespace": "MyApp",
        "routing": false
    } );
    
    MyApp.subscribeWith( {
        "TAPROOT|START": () => {
            document.body.innerHTML = "My application started up!";
        }
    } );
    
    MyApp.start();
}

start();

Writing an Application

import { setup } from "https://cdn.skypack.dev/@thomasrandolph/taproot";

async function start(){
    var MyApp = await setup( {
        "namespace": "MyApp",
        "routing": {
            "routes": [
                [
                    "/",
                    () => {
                        document.body.innerHTML = `Hello, world! Go to <a href="/account/put-your-name-here">/account/[your name]</a>!`;
                    }
                ],
                [
                    "/account/:name",
                    ( context ) => {
                        document.body.innerHTML = `Hello, ${context.params.name}`;
                    }
                ]
            ]
        }
    } );
    
    MyApp.start();
}

start();

Now you have a working application with routing!
But we should leverage the powerful message bus provided by taproot.

import { setup } from "https://cdn.skypack.dev/@thomasrandolph/taproot";
import { publish } from "https://cdn.skypack.dev/@thomasrandolph/taproot/MessageBus/MessageBus.js";

async function start(){
    var MyApp = await setup( {
        "namespace": "MyApp",
        "routing": {
            "routes": [
                [ "/", () => publish( { "name": "VIEW_CHANGE", "view": "home" } ) ],
                [ "/account/:name", ( context ) => publish( { "name": "VIEW_CHANGE", "view": "account", context } ) ]
            ]
        }
    } );

    MyApp.subscribeWith( {
        "VIEW_CHANGE": ( message ) => {
            let views = {
                "home": () => document.body.innerHTML = `Hello, world! <br /><br /> Go to <a href="/account/put-your-name-here">/account/[your name]</a>`,
                "account": ( msg ) => document.body.innerHTML = `Hello, ${msg.context.params.name}`,
                "error": () => document.body.innerHTML = "There was an error trying to route you."
            };

            if( views[ message.view ] ){
                views[ message.view ]( message );
            }
            else{
                views.error();
            }
        }
    } );
    
    MyApp.start();
}

start();

Advanced Installation

Use esinstall to create importable libraries

Install esinstall: npm install -E -D esinstall

Run a script for all your dependencies:

import { install } from "esinstall";

async function run(){
await install(
    [
        "@thomasrandolph/taproot",
        "@thomasrandolph/taproot/MessageBus"
        // Etc.
    ],
    {
        "sourceMap": false,
        "dest": "./web_modules/",
        "treeshake": true
    }
);
}

run();

When you import the module, use web_modules/@thomasrandolph/taproot.js
Repeat step 2 whenever your dependencies change (this can be automated, for example as a postinstall hook)

Use other bundling options

Any combination of bundlers and transpilers can resolve bare module specifiers into something that works on the web.

As long as your bundler understands ECMAScript Modules (the standard module specification for JavaScript), you can use taproot in your build pipeline.

Usage no npm install needed!