@overlook/router-ordered NPM

DEPRECATED

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

Overlook framework ordered router

Abstract

Route class extension for routes which need to be in a certain order relative to their siblings in their mutual parent's array of children.

e.g. For path-matching routes, /photos/new needs to be before /photos/:id so it gets a chance to be matched first.

Usage

Where to use it

This extension should be on the routes which need to be ordered, not the parent containing them. i.e. on /photos/new and /photos/:id, not /photos.

Defining order

Each route can say that it needs to be before or after any other of its siblings.

It can do this by extending the [IS_BEFORE]() method.

[IS_BEFORE]() will be called with each of the route's siblings. It can return:

true if needs to be before that sibling
false if needs to be after that sibling
null if no preference

The default [IS_BEFORE]() method provided by the extension returns null (i.e. no preference).

const Route = require('@overlook/route');
const orderedExtension = require('@overlook/router-ordered');
const {IS_BEFORE} = orderedExtension;
const RouteOrdered = Route.extend( orderedExtension );

class MyOrderedRoute extends RouteOrdered {
  [IS_BEFORE](sibling) {
    // If super method returns a result, use it
    const before = super[IS_BEFORE](sibling);
    if (before !== null) return before;

    // Sort in alphabetical order
    if (this.name === sibling.name) return null;
    return this.name < sibling.name ? true : false;
  }
}

Conflicts

Ordering occurs in the init phase.

Every sibling will be asked where it wants to be relative to every other sibling.

Conflicts can occur if A says it's before B and B says it's before A, or there's a circular relationship (A before B, B before C, C before A).

In these cases an error will be thrown.

Extending

The extension also exposes an [ORDER]() method.

If you want to take some action before/after ordering, extend this method.

NB After [ORDER](), this route will be in correct order as per its preferences, but all its siblings are not neccesarily in their final order. It's possible a later sibling may switch positions with another sibling once it's [ORDER]() method has been called.