4.1.22 • Published 4 months ago

@thi.ng/router v4.1.22

Weekly downloads
285
License
Apache-2.0
Repository
github
Last release
4 months ago

router

npm version npm downloads Twitter Follow

This project is part of the @thi.ng/umbrella monorepo.

About

Generic router for browser & non-browser based applications.

  • Declarative route definitions
  • Parametric routes, each param with optional value coercion & validation
  • Route authentication handler to enable/disable routes based on other state factors
  • Fallback route
  • Enforced initial route (optional)
  • Route formatting (with params)
  • HTML5 history & hash fragment support

Partially based on the Clojure implementation in thi.ng/domus.

Status

STABLE - used in production

Search or submit any issues for this package

Related packages

  • @thi.ng/hdom - Lightweight vanilla ES6 UI component trees with customizable branch-local behaviors
  • @thi.ng/rdom - Lightweight, reactive, VDOM-less UI/DOM components with async lifecycle and @thi.ng/hiccup compatible

Installation

yarn add @thi.ng/router

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/router"></script>

Skypack documentation

For Node.js REPL:

# with flag only for < v16
node --experimental-repl-await

> const router = await import("@thi.ng/router");

Package sizes (gzipped, pre-treeshake): ESM: 1.53 KB

Dependencies

Usage examples

Several demos in this repo's /examples directory are using this package.

A selection:

ScreenshotDescriptionLive demoSource
Complete mini SPA app w/ router & async content loadingDemoSource

API

Generated API docs

import { HTMLRouter, EVENT_ROUTE_CHANGED } from "@thi.ng/router";

// router configuration
const config = {

    // use hash fragment for routes
    useFragment: true,

    // fallback route (when no other matches)
    defaultRouteID: "home",

    // optional enforced route when router starts
    initialRouteID: "home",

    // Optional route path component separator. Default: `/`
    separator: "/",

    // Route prefix. Default: `/`. All routes to be parsed by `route()`
    // are assumed to have this prefix. All routes returned by
    // `format()` will include this prefix.
    prefix: "/",

    // actual route defs
    // these are checked in given order
    // IMPORTANT: rules with common prefixes MUST be specified in
    // order of highest precision / longest path
    routes: [
        {
            // each route MUST have an ID
            id: "home",
            // optional title for UI purposes (no internal function)
            title: "Home page",
            // this array defines the route path items
            match: ["home"]
        },
        {
            id: "user-profile",
            // this rule is parametric
            // variable items are prefixed with `?`
            match: ["users", "?id"],
            // coercion & validation handlers for "?id" param
            // coercion fn is applied BEFORE validator
            validate: {
                id: {
                    coerce: (x) => parseInt(x),
                    check: (x)=> x > 0 && x < 100
                }
            }
        },
        {
            id: "image",
            // this route has 2 params and matches (for example):
            // "/images/07a9d87b-c07a-42e3-82cf-baea2f94facc/xl"
            match: ["images", "?id", "?size"],
            validate: {
                id: {
                    check: (x)=> isUUID(x)
                },
                size: {
                    check: (x)=> /^(s|m|l|xl)$/.test(x)
                }
            },
            // enable auth for this route
            // (see info about authenticator functions below)
            auth: true
        },
        {
            id: "group-list",
            // matches only: "/users" or "/images"
            match: ["?type"],
            validate: {
                type: {
                    check: (x) => /^(users|images)$/.test(x)
                }
            },
            auth: true
        },
    ]
};

// `HTMLRouter` ONLY works in browser environments
// for non-browser use cases use `BasicRouter`
const router = new HTMLRouter(config);
router.addListener(EVENT_ROUTE_CHANGED, console.log);

router.start();

See further comments in source code

Authors

Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-router,
  title = "@thi.ng/router",
  author = "Karsten Schmidt",
  note = "https://thi.ng/router",
  year = 2014
}

License

© 2014 - 2021 Karsten Schmidt // Apache Software License 2.0

4.1.22

4 months ago

4.1.21

4 months ago

4.1.20

5 months ago

4.1.19

5 months ago

4.1.16

6 months ago

4.1.17

5 months ago

4.1.18

5 months ago

4.1.15

6 months ago

4.1.14

6 months ago

4.1.13

6 months ago

4.1.12

6 months ago

4.1.11

7 months ago

4.1.10

8 months ago

4.1.9

8 months ago

4.1.8

9 months ago

4.1.7

10 months ago

4.0.12

1 year ago

4.0.11

1 year ago

4.1.4

12 months ago

4.1.3

12 months ago

4.1.6

11 months ago

4.1.5

11 months ago

4.1.0

1 year ago

4.1.2

12 months ago

4.1.1

1 year ago

4.0.10

1 year ago

4.0.9

1 year ago

4.0.8

1 year ago

4.0.7

1 year ago

4.0.6

1 year ago

4.0.5

1 year ago

4.0.4

1 year ago

4.0.3

1 year ago

4.0.2

1 year ago

4.0.1

1 year ago

4.0.0

1 year ago

3.4.0

1 year ago

3.3.0

1 year ago

3.2.62

1 year ago

3.2.61

1 year ago

3.2.60

1 year ago

3.2.59

1 year ago

3.2.57

1 year ago

3.2.58

1 year ago

3.2.56

1 year ago

3.2.55

1 year ago

3.2.53

1 year ago

3.2.52

1 year ago

3.2.54

1 year ago

3.2.50

1 year ago

3.2.49

1 year ago

3.2.48

2 years ago

3.2.47

2 years ago

3.2.46

2 years ago

3.2.45

2 years ago

3.2.44

2 years ago

3.2.43

2 years ago

3.2.35

2 years ago

3.2.34

2 years ago

3.2.37

2 years ago

3.2.36

2 years ago

3.2.38

2 years ago

3.2.30

2 years ago

3.2.33

2 years ago

3.2.32

2 years ago

3.2.40

2 years ago

3.2.42

2 years ago

3.2.41

2 years ago

3.2.29

2 years ago

3.2.28

2 years ago

3.2.27

2 years ago

3.2.24

2 years ago

3.2.26

2 years ago

3.2.25

2 years ago

3.2.23

2 years ago

3.2.20

2 years ago

3.2.22

2 years ago

3.2.17

3 years ago

3.2.16

3 years ago

3.2.19

2 years ago

3.2.18

3 years ago

3.2.9

3 years ago

3.2.8

3 years ago

3.2.7

3 years ago

3.2.13

3 years ago

3.2.12

3 years ago

3.2.15

3 years ago

3.2.14

3 years ago

3.2.11

3 years ago

3.2.10

3 years ago

3.2.6

3 years ago

3.2.5

3 years ago

3.2.2

3 years ago

3.2.1

3 years ago

3.2.0

3 years ago

3.2.4

3 years ago

3.2.3

3 years ago

3.1.7

3 years ago

3.1.6

3 years ago

3.1.8

3 years ago

3.1.5

3 years ago

3.1.4

3 years ago

3.1.3

4 years ago

3.1.2

4 years ago

3.1.1

4 years ago

3.1.0

4 years ago

3.0.8

4 years ago

3.0.7

4 years ago

3.0.4

4 years ago

3.0.6

4 years ago

3.0.3

4 years ago

3.0.2

4 years ago

3.0.1

4 years ago

3.0.0

4 years ago

2.0.54

4 years ago

2.0.53

4 years ago

2.0.51

4 years ago

2.0.52

4 years ago

2.0.50

4 years ago

2.0.49

4 years ago

2.0.48

4 years ago

2.0.47

4 years ago

2.0.46

4 years ago

2.0.45

4 years ago

2.0.44

4 years ago

2.0.42

4 years ago

2.0.43

4 years ago

2.0.41

4 years ago

2.0.40

4 years ago

2.0.39

4 years ago

2.0.38

5 years ago

2.0.37

5 years ago

2.0.36

5 years ago

2.0.35

5 years ago

2.0.34

5 years ago

2.0.33

5 years ago

2.0.32

5 years ago

2.0.31

5 years ago

2.0.30

5 years ago

2.0.29

5 years ago

2.0.28

5 years ago

2.0.27

5 years ago

2.0.26

5 years ago

2.0.25

5 years ago

2.0.24

5 years ago

2.0.23

5 years ago

2.0.22

5 years ago

2.0.21

5 years ago

2.0.20

5 years ago

2.0.19

5 years ago

2.0.18

5 years ago

2.0.17

5 years ago

2.0.16

5 years ago

2.0.15

5 years ago

2.0.14

5 years ago

2.0.13

5 years ago

2.0.11

5 years ago

2.0.12

5 years ago

2.0.10

5 years ago

2.0.9

5 years ago

2.0.8

5 years ago

2.0.7

6 years ago

2.0.6

6 years ago

2.0.5

6 years ago

2.0.4

6 years ago

2.0.3

6 years ago

2.0.2

6 years ago

2.0.1

6 years ago

2.0.0

6 years ago

1.0.12

6 years ago

1.0.11

6 years ago

1.0.10

6 years ago

1.0.9

6 years ago

1.0.8

6 years ago

1.0.7

6 years ago

1.0.6

6 years ago

1.0.5

6 years ago

1.0.4

6 years ago

1.0.3

6 years ago

1.0.2

6 years ago

1.0.1

6 years ago

1.0.0

6 years ago

0.1.30

7 years ago

0.1.29

7 years ago

0.1.28

7 years ago

0.1.27

7 years ago

0.1.26

7 years ago

0.1.25

7 years ago

0.1.24

7 years ago

0.1.24-alpha.0

7 years ago

0.1.23

7 years ago

0.1.22

7 years ago

0.1.21

7 years ago

0.1.20

7 years ago

0.1.19

7 years ago

0.1.18

7 years ago

0.1.17

7 years ago

0.1.16

7 years ago

0.1.14

7 years ago

0.1.13

7 years ago

0.1.12

7 years ago

0.1.11

7 years ago

0.1.10

7 years ago

0.1.9

7 years ago

0.1.8

7 years ago

0.1.7

7 years ago

0.1.6

7 years ago

0.1.5

7 years ago

0.1.4

7 years ago

0.1.3

7 years ago

0.1.2

7 years ago

0.1.1

7 years ago

0.1.0

7 years ago