@overlook/router NPM

DEPRECATED

This package has been renamed @overlook/plugin. Please use that instead.

Overlook framework Router class

Introduction

Overlook framework Router class. Route class extensions (otherwise known as "Routers") should be created with this class.

Overlook is intended to be extremely modular and flexible.

The base Route class has very little functionality, and most functionality is intended to be added using Routers.

Extensions (or "Routers") are much like "plugins", which other frameworks use, but the main difference is this:

Route class extensions apply at the route level, not application level.

One route, or subtree of routes, can have one behavior, another subtree can have another. So, for example, one part of the app can use React, another part can server-render pages from EJS templates.

This architecture allows:

"Snap in" extensions providing common functionality, making building apps fast
Granular control over every route's individual behavior

Usage

Creating a Router

A Router is created from a function which receives a Route class and should return a subclass of it.

const Router = require('@overlook/router'),
  makeSymbols = require('@overlook/util-make-symbols');

const { TYPE, GREETING } = makeSymbols(
  [ 'TYPE', 'GREETING' ]
);

const mammalRouter = new Router( Route => (
  class extends Route {
    initProps( props ) {
      super.initProps( props );
      this[TYPE] = undefined;
    }

    initRoute( app ) {
      super.initRoute( app );
      if (this[TYPE] === undefined) this[TYPE] = 'mammal';
    }

    [GREETING]() {
      return `Hello, I am a ${this[TYPE]}.`;
    }
  }
) );

mammalRouter.TYPE = TYPE;
mammalRouter.GREETING = GREETING;

New methods and properties should have Symbol keys, not strings. If properties are intended to be accessed by other Routers, or methods intended to be available for extending, the Symbol should be exported as a property of the Router.

The Router can than be used create a subclass of a Route class, using .extend():

const Route = require('@overlook/route');

const MammalRoute = Route.extend( mammalRouter );

That subclass can now be used to create a route which includes the Router's functionality:

const route = new MammalRoute();

route[ mammalRouter.GREETING ]()
// => 'Hello, I am a mammal.'

Removing Symbols boilerplate

It's typical for a Router to define Symbols.

To reduce boilerplate code, you can create Symbols within the Router constructor.

This example is equivalent to the first:

const Router = require('@overlook/router');

const mammalRouter = new Router( {
  symbols: [ 'TYPE', 'GREETING' ],
  extend
} );

const { TYPE, GREETING } = mammalRouter;

function extend( Route ) (
  class extends Route {
    initProps( props ) {
      super.initProps( props );
      this[TYPE] = undefined;
    }

    initRoute( app ) {
      super.initRoute( app );
      if (this[TYPE] === undefined) this[TYPE] = 'mammal';
    }

    [GREETING]() {
      return `Hello, I am a ${this[TYPE]}.`;
    }
  }
}

Note that the symbols were set as properties of mammalRouter.

Publishing a Router to NPM

new Router() has a few more options which should be used when publishing a Router to NPM.

You should pass in the name and version of the module.
Symbols must be created using either @overlook/util-make-symbols or the Router constructor.

// Published as `@me/monkey`
// version 1.0.0
const Router = require('@overlook/router'),
  makeSymbols = require('@overlook/util-make-symbols');

const { GREETING } = makeSymbols(
  '@me/monkey',
  [ 'GREETING' ]
);

const monkeyRouter = new Router(
  {
    name: '@me/monkey',
    version: '1.0.0'
  },
  Route => class extends Route { /* ... */ }
);

module.exports = monkeyRouter;

The options object has the same properties as package.json so, to avoid having to update the version property every time you publish a new version of the module, you can pass that instead.

It's also more economical to create symbols in new Router(), to avoid passing the package name to makeSymbols() too:

const pkg = require('./package.json');

const monkeyRouter = new Router(
  pkg,
  { symbols: [ 'GREETING' ] },
  Route => class extends Route { /* ... */ }
);

module.exports = monkeyRouter;

Longer example including using symbols

const Router = require('@overlook/router');
const pkg = require('./package.json');

const monkeyRouter = new Router(
  pkg,
  { symbols: [ 'GREETING' ] },
  extend
);

const { GREETING } = monkeyRouter;

function extend( Route ) {
  return class extends Route {
    [GREETING]() {
      return 'Hello, I am a monkey.';
    }
  };
}

module.exports = monkeyRouter;

Composing Routers

Routers can extend other Routers.

Let's say we have various routes which need a "greeting" method. This functionality can be split off into its own Router.

const Router = require('@overlook/router');

const typeRouter = new Router(
  { symbols: [ 'TYPE', 'GET_TYPE', 'GREETING' ] },
  extend
} );

const { TYPE, GET_TYPE, GREETING } = typeRouter;

function extend( Route ) (
  class extends Route {
    initProps( props ) {
      super.initProps( props );
      this[TYPE] = undefined;
    }

    initRoute( app ) {
      super.initRoute( app );
      this[TYPE] = this[GET_TYPE]();
    }

    [GET_TYPE]() {
      return 'mystery';
    }

    [GREETING]() {
      return `Hello, I am a ${this[TYPE]}.`;
    }
  }
}

Now other Routers can extend off that:

const { GET_TYPE } = typeRouter;

const monkeyRouter = new Router(
  Route => {
    Route = Route.extend( typeRouter );

    return class extends Route {
      [GET_TYPE]() {
        return 'monkey';
	  }
    };
  }
);

const zebraRouter = new Router(
  Route => {
    Route = Route.extend( typeRouter );

    return class extends Route {
      [GET_TYPE]() {
        return 'zebra';
	  }
    };
  }
);

const MonkeyRoute = Route.extend( monkeyRouter );
const monkey = new MonkeyRoute();
monkey[GREETNG]()
// => 'Hello, I am a monkey.'

const ZebraRoute = Route.extend( zebraRouter );
const zebra = new ZebraRoute();
zebra[GREETNG]()
// => 'Hello, I am a zebra.'