• Stars
    star
    132
  • Rank 274,205 (Top 6 %)
  • Language
    JavaScript
  • License
    BSD 2-Clause "Sim...
  • Created about 8 years ago
  • Updated over 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A simple routing library for ClojureScript

bide

Clojars Project

Introduction

A simple routing library for ClojureScript that uses Express-like syntax.

Egiak ez ditu bi bide

β€” A Basque proverb.
Note
Looking for a maintainer.

Install

Add the following dependency to your project.clj file:

[funcool/bide "1.7.0"]

User Guide

Just import the core namespace and start building the router:

(ns myapp.core
  (:require [bide.core :as r]))

(def router
  (r/router [["/api/auth" :myapp/auth]
             ["/api/users/:id" :myapp/user-by-id]]))

Now, you can perform basic operations such as match and resolve:

(r/match router "/api/auth")
;; => [:myapp/auth nil nil]

(r/match router "/api/users/1")
;; => [:myapp/user-by-id {:id "1"} nil]

(r/match router "/api/users/1?foobar=1")
;; => [:myapp/user-by-id {:id "1"} {:foobar "1"}]

(r/match router "/api/other")
;; => nil

(r/resolve router :myapp/auth)
;; => "/api/auth"

(r/resolve router :myapp/user-by-id {:id 2})
;; => "/api/users/2"

(r/resolve router :myapp/user-by-id {:id 2} {:foobar 1})
;; => "/api/users/2?foobar=1"

In addition, you can integrate it in your ClojureScript web application using the provided builtin helpers. It uses goog.History API under the hood:

(defn on-navigate
  "A function which will be called on each route change."
  [name params query]
  (println "Route change to: " name params query))

(r/start! router {:default :myapp/auth
                  :on-navigate on-navigate})

Also, you can pass factory function that returns instance of goog.history.Html5History as value of :html5history key of second argument and bide would use it to manage history events, and/or pass true as value of :html5? key to stop using '#' in URLs.

Note that when :html5? is true, the built-in instance of Html5History uses a custom goog.history.Html5History.TokenTransformer to allow it to handle query parameters. You can construct a transformer with token-transformer.

Finally, you can force the navigation trigger by using the navigate! helper function:

(r/navigate! router :myapp/user-by-id {:id 10})

Or if you don’t want to add entry into history use replace! helper function instead.

How to Contribute?

Just open an issue or PR ;)

FAQ

Why another routing library?

Existing solutions out there are complex and generally bloated wih irrelevant documentation.

Most libraries work with native Clojure data structures for representing the routing configuration. It’s a great idea, but it does not work very well once your project scales. Things get out of hand pretty fast.

An example of this with bidi routing library:

(def routes
  ["/" [["auth/login" :auth/login]
        [["auth/recovery/token/" :token] :auth/recovery]
        ["workspace/" [[[:project-uuid "/" :page-uuid] :workspace/page]]]]])

The mental effort required to read and understand the configuration defined like this is considerable. Now, let’s see an example using bide:

(def routes
  [["/auth/login" :auth/login]
   ["/auth/recovery/token/:token" :auth/recovery]
   ["/workspace/:project-uuid/:page-uuid" :workspace/page]])

As you can imagine, a simple library like bide does not offer all the features provided by other solutions. New features will be added on-demand. However, we plan to stay as small and simple as possible.

How fast is bide?

Before talking about real performance comparisons and benchmarks, you should know that bide design is very simple and maybe can be considered naive. The worst case for the matching algorithm is O(N) and O(1) for resolve operation.

Considering that having thousands of entries is very unlikely to happen, the match algorithm works pretty well. This is a comparison against the same operations with bidi:

$ node out/benchmarks.js
op=resolve lib=bidi ops=10000
"Elapsed time: 90.989215 msecs"
op=resolve lib=bide ops=10000
"Elapsed time: 19.447844 msecs"
op=match lib=bidi ops=10000
"Elapsed time: 1070.330668 msecs"
op=match lib=bide ops=10000
"Elapsed time: 98.864120 msecs"

I’ve been a bidi user for quite some time, that’s why I choose this library to run the benchmarks.

License

bide is licensed under BSD (2-Clause) license.

More Repositories

1

cats

Category Theory and Algebraic abstractions for Clojure and ClojureScript.
Clojure
938
star
2

buddy

Security library for Clojure
Clojure
827
star
3

promesa

A promise library & concurrency toolkit for Clojure and ClojureScript.
Clojure
491
star
4

clojurescript-unraveled

An open source book about ClojureScript
XSLT
474
star
5

cuerdas

String manipulation library for Clojure(Script)
Clojure
304
star
6

buddy-auth

Authentication and Authorization facilities for ring and ring based web applications.
Clojure
292
star
7

catacumba

Asynchronous web toolkit for clojure built on top of Ratpack / Netty
Clojure
193
star
8

beicon

Reactive Streams for ClojureScript
JavaScript
152
star
9

buddy-core

Cryptographic api for Clojure
Clojure
145
star
10

urania

Elegant and Efficient remote data access for Clojure(Script)
Clojure
138
star
11

struct

Structural validation library for Clojure(Script)
Clojure
119
star
12

buddy-sign

High level message signing library.
Clojure
118
star
13

clojure.jdbc

JDBC library for Clojure
Clojure
105
star
14

lentes

Functional references for Clojure and ClojureScript
Clojure
93
star
15

rumext

Simple and decomplected ui library for ClojureScript (based on React)
Clojure
88
star
16

suricatta

High level sql toolkit for clojure (backed by jooq library)
Clojure
83
star
17

octet

A library that makes working with bytebuffers painless.
Clojure
83
star
18

buddy-hashers

Collection of password hashers.
Java
76
star
19

httpurr

A ring-inspired, promise-returning, simple Clojure(Script) HTTP client.
Clojure
67
star
20

hodgepodge

A idiomatic ClojureScript interface to local and session storage
Clojure
66
star
21

datoteka

A filesystem toolset and storage implementation for Clojure.
Clojure
58
star
22

potok

Reactive streams based state management toolkit for ClojureScript
Clojure
43
star
23

codeina

Api documentation generator for Clojure and ClojureScript (codox fork)
Clojure
29
star
24

tubax

Clojurescript XML parser
JavaScript
24
star
25

promissum

DEPRECATED: use funcool/promesa
Clojure
18
star
26

vertx-clojure

A lightweight clojure adapter for vertx toolkit.
Clojure
17
star
27

boot-codeina

Beautiful api documentation generator for Clojure.
Clojure
14
star
28

decimal

An arbitrary-precision Decimal type for ClojureScript
JavaScript
13
star
29

yetti

Adapter for Ring (with H2C and WebSocket support).
Clojure
11
star
30

okulary

Fast Atom and DerivedAtom for ClojureScript.
Clojure
9
star
31

canal

DEPRECATED: A channel monad for cats library
Clojure
7
star
32

fs

File system utilities for Clojure (helpers for java.io.File)
Clojure
7
star
33

tools

A general purpose set of utils for Clojure & Clojurescript (Logging, Exceptions, ...)
Clojure
7
star
34

dost

A cryptographic API & signing toolkit for ClojureScript (nodejs target only) (wip)
Clojure
6
star
35

rxhttp

A reactive streams based http client for ClojureScript
Clojure
6
star
36

clojure-course

A Clojure & ClojureScript course material
6
star
37

zaek

A lightweight RabbitMQ client for Clojure (built on top of java client).
Clojure
5
star
38

log4j2-clojure

A clojure specific appender implementation for Log4j2.
Java
4
star
39

cljs-testrunners

ClojureScript test runners facilities/helpers.
Clojure
4
star
40

wydra

Messaging library for Clojure
Clojure
4
star
41

futura

DEPRECATED
Clojure
4
star
42

catacumba-prone

A prone (error reporting middleware) integration for catacumba.
Clojure
3
star
43

funcool.github.io

Clojure
3
star
44

postal

A postal client for ClojureScript
Clojure
2
star
45

web

HTML
1
star
46

bootutils

A collection tasks for boot for deploy and similar operations.
Clojure
1
star
47

doc

funcool homepage
CSS
1
star