Nostalgic Perogi Monogramming

    navaid
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.0 • Public • Published
    navaid
    A navigation aid (aka, router) for the browser in 865 bytes~!

    Install

    $ npm install --save navaid
    

    Usage

    const navaid = require('navaid');
     
    // Setup router
    let router = navaid();
    // or: new Navaid();
     
    // Attach routes
    router
      .on('/', () => {
        console.log('~> /');
      })
      .on('/users/:username', params => {
        console.log('~> /users/:username', params);
      })
      .on('/books/*', params => {
        console.log('~> /books/*', params);
      });
     
    // Run as single instance
    router.run('/');
    //=> "~> /"
    router.run('/users/lukeed');
    //=> "~> /users/:username { username: 'lukeed' }"
    router.run('/books/kids/narnia');
    //=> "~> /books/* { wild: 'kids/narnia' }"
     
    // Run as long-lived router w/ history & "<a>" bindings
    // Also immediately calls `run()` handler for current location
    router.listen();

    API

    navaid(base, on404)

    Returns: Navaid

    base

    Type: String
    Default: '/'

    The base pathname for your application. By default, Navaid assumes it's operating on the root.

    All routes will be processed relative to this path (see on()). Similarly, while listening, Navaid will not intercept any links that don't lead with this base pathname.

    Note: Navaid will accept a base with or without a leading and/or trailing slash, as all cases are handled identically.

    on404

    Type: Function
    Default: undefined

    The function to run if the incoming pathname did not match any of your defined defined patterns.
    When defined, this function will receive the formatted uri as its only parameter; see format().

    Important: Navaid only processes routes that match your base path!
    Put differently, on404 will never run for URLs that do not begin with base.
    This allows you to mount multiple Navaid instances on the same page, each with different base paths. 😉

    format(uri)

    Returns: String or false

    Formats and returns a pathname relative to the base path.

    If the uri does not begin with the base, then false will be returned instead.
    Otherwise, the return value will always lead with a slash (/).

    Note: This is called automatically within the listen() and run() methods.

    uri

    Type: String

    The path to format.

    Note: Much like base, paths with or without leading and trailing slashes are handled identically.

    route(uri, replace)

    Returns: undefined

    Programmatically route to a path whilst modifying & using the history events.

    uri

    Type: String

    The desired path to navigate.

    Important: Navaid will prefix your uri with the base, if/when defined.

    replace

    Type: Boolean
    Default: false

    If true, then history.replaceState will be used. Otherwise history.pushState will be used.

    This is generally used for redirects; for example, redirecting a user away from a login page if they're already logged in.

    on(pattern, handler)

    Returns: Navaid

    Define a function handler to run when a route matches the given pattern string.

    pattern

    Type: String

    The supported pattern types are:

    • static (/users)
    • named parameters (/users/:id)
    • nested parameters (/users/:id/books/:title)
    • optional parameters (/users/:id?/books/:title?)
    • any match / wildcards (/users/*)

    Note: It does not matter if your pattern begins with a / — it will be added if missing.

    handler

    Type: Function

    The function to run when its pattern is matched.

    Note: This can also be a Promise or async function, but it's up to you to handle its result/error.

    For patterns with named parameters and/or wildcards, the handler will receive an "params" object containing the parsed values.

    When wildcards are used, the "params" object will fill a wild key with the URL segment(s) that match from that point & onward.

    let r = new Navaid();
     
    r.on('/users/:id', console.log).run('/users/lukeed');
    //=> { id: 'lukeed' }
     
    r.on('/users/:id/books/:title?', console.log).run('/users/lukeed/books/narnia');
    //=> { id: 'lukeed', title: 'narnia' }
     
    r.on('/users/:id/jobs/*').run('/users/lukeed/jobs/foo/bar/baz/bat');
    //=> { id: 'lukeed', wild: 'foo/bar/baz/bat' }

    run(uri)

    Returns: Navaid

    Executes the matching handler for the specified path.

    Unlike route(), this does not pass through the history state nor emit any events.

    Note: You'll generally want to use listen() instead, but run() may be useful in Node.js/SSR contexts.

    uri

    Type: String
    Default: location.pathname

    The pathname to process. Its matching handler (as defined by on()) will be executed.

    listen(uri?)

    Returns: Navaid

    Attaches global listeners to synchronize your router with URL changes, which allows Navaid to respond consistently to your browser's BACK and FORWARD buttons.

    These are the (global) events that Navaid creates and/or responds to:

    • popstate
    • replacestate
    • pushstate

    Navaid will also bind to any click event(s) on anchor tags (<a href="" />) so long as the link has a valid href that matches the base path. Navaid will not intercept links that have any target attribute or if the link was clicked with a special modifier (eg; ALT, SHIFT, CMD, or CTRL).

    uri

    Type: String
    Default: undefined

    (Optional) Any value passed to listen() will be forwarded to the underlying run() call.
    When not defined, run() will read the current location.pathname value.

    unlisten()

    Returns: undefined

    Detach all listeners initialized by listen().

    Note: This method is only available after listen() has been invoked.

    License

    MIT © Luke Edwards

    Install

    npm i navaid

    DownloadsWeekly Downloads

    268

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    16.5 kB

    Total Files

    7

    Last publish

    Collaborators

    • lukeed