Nationwide Polamorous Matrimony

    nbb

    0.1.1 • Public • Published

    Not babashka. Node.js babashka!?

    Ad-hoc CLJS scripting on Node.js.

    Status

    Experimental. Please report issues here.

    Goals and features

    Nbb's main goal is to make it easy to get started with ad hoc CLJS scripting on Node.js.

    Additional goals and features are:

    • Fast startup without relying on a custom version of Node.js.
    • Small artifact (current size is around 1.2MB).
    • First class macros.
    • Support building small TUI apps using Reagent.
    • Complement babashka with libraries from the Node.js ecosystem.

    Community

    Requirements

    Nbb requires Node.js v12 or newer.

    How does this tool work?

    CLJS code is evaluated through SCI, the same interpreter that powers babashka. Because SCI works with advanced compilation, the bundle size, especially when combined with other dependencies, is smaller than what you get with self-hosted CLJS. That makes startup faster. The trade-off is that execution is less performant and that only a subset of CLJS is available (e.g. no deftype, yet).

    Usage

    Install nbb from NPM:

    $ npm install nbb -g
    

    Omit -g for a local install.

    Try out an expression:

    $ nbb -e '(+ 1 2 3)'
    6

    And then install some other NPM libraries to use in the script. E.g.:

    $ npm install csv-parse shelljs term-size zx
    

    Create a script which uses the NPM libraries:

    (ns script
      (:require ["csv-parse/lib/sync$default" :as csv-parse]
                ["fs" :as fs]
                ["path" :as path]
                ["shelljs$default" :as sh]
                ["term-size$default" :as term-size]
                ["zx$default" :as zx]
                ["zx$fs" :as zxfs]
                [nbb.core :refer [*file*]]))
    
    (prn (path/resolve "."))
    
    (prn (term-size))
    
    (println (count (str (fs/readFileSync *file*))))
    
    (prn (sh/ls "."))
    
    (prn (csv-parse "foo,bar"))
    
    (prn (zxfs/existsSync *file*))
    
    (zx/$ #js ["ls"])

    Call the script:

    $ nbb script.cljs
    "/private/tmp/test-script"
    #js {:columns 216, :rows 47}
    510
    #js ["node_modules" "package-lock.json" "package.json" "script.cljs"]
    #js [#js ["foo" "bar"]]
    true
    $ ls
    node_modules
    package-lock.json
    package.json
    script.cljs
    

    What does $default mean?

    The :default foo syntax is shadow-cljs only and not supported by vanilla CLJS (and nbb doesn't support it either). The $default syntax is a recent addition to CLJS and should work in shadow-cljs too: this is why nbb supports it too.

    See here for more infor on that syntax.

    Nbb implements :require via dynamic import (import() in JS). This is why you need to add $default to imports when you want to import the default object from a module.

    Macros

    Nbb has first class support for macros: you can define them right inside your .cljs file, like you are used to from JVM Clojure. Consider the plet macro to make working with promises more palatable:

    (defmacro plet
      [bindings & body]
      (let [binding-pairs (reverse (partition 2 bindings))
            body (cons 'do body)]
        (reduce (fn [body [sym expr]]
                  (let [expr (list '.resolve 'js/Promise expr)]
                    (list '.then expr (list 'clojure.core/fn (vector sym)
                                            body))))
                body
                binding-pairs)))

    Using this macro we can look async code more like sync code. Consider this puppeteer example:

    (-> (.launch puppeteer)
          (.then (fn [browser]
                   (-> (.newPage browser)
                       (.then (fn [page]
                                (-> (.goto page "https://clojure.org")
                                    (.then #(.screenshot page #js{:path "screenshot.png"}))
                                    (.catch #(js/console.log %))
                                    (.then #(.close browser)))))))))

    Using plet this becomes:

    (plet [browser (.launch puppeteer)
           page (.newPage browser)
           _ (.goto page "https://clojure.org")
           _ (-> (.screenshot page #js{:path "screenshot.png"})
                 (.catch #(js/console.log %)))]
          (.close browser))

    See the puppeteer example for the full code.

    Since v0.0.36, nbb includes promesa which is a library to deal with promises. The above plet macro is similar to promesa.core/let.

    Startup time

    $ time nbb -e '(+ 1 2 3)'
    6
    nbb -e '(+ 1 2 3)'   0.17s  user 0.02s system 109% cpu 0.168 total

    The baseline startup time for a script is about 170ms seconds on my laptop. When invoked via npx this adds another 300ms or so, so for faster startup, either use a globally installed nbb or use $(npm bin)/nbb script.cljs to bypass npx.

    Dependencies

    NPM dependencies

    Nbb does not depend on any NPM dependencies. All NPM libraries loaded by a script are resolved relative to that script. When using the Reagent module, React is resolved in the same way as any other NPM library.

    Classpath

    To load .cljs files from local paths or dependencies, you can use the --classpath argument. The current dir is added to the classpath automatically. So if there is a file foo/bar.cljs relative to your current dir, then you can load it via (:require [foo.bar :as fb]). Note that nbb uses the same naming conventions for namespaces and directories as other Clojure tools: foo-bar in the namespace name becomes foo_bar in the directory name.

    To load dependencies from the Clojure ecosystem, you can use the Clojure CLI or babashka to download them and produce a classpath:

    $ classpath="$(clojure -A:nbb -Spath -Sdeps '{:aliases {:nbb {:replace-deps {com.github.seancorfield/honeysql {:git/tag "v2.0.0-rc5" :git/sha "01c3a55"}}}}}')"

    and then feed it to the --classpath argument:

    $ nbb --classpath "$classpath" -e "(require '[honey.sql :as sql]) (sql/format {:select :foo :from :bar :where [:= :baz 2]})"
    ["SELECT foo FROM bar WHERE baz = ?" 2]

    Currently nbb only reads from directories, not jar files, so you are encouraged to use git libs. Support for .jar files will be added later.

    Current file

    The name of the file that is currently being executed is available via nbb.core/*file* or on the metadata of vars:

    (ns foo
      (:require [nbb.core :refer [*file*]]))
    
    (prn *file*) ;; "/private/tmp/foo.cljs"
    
    (defn f [])
    (prn (:file (meta #'f))) ;; "/private/tmp/foo.cljs"

    Reagent

    Nbb includes reagent.core which will be lazily loaded when required. You can use this together with ink to create a TUI application:

    $ npm install ink
    

    ink-demo.cljs:

    (ns ink-demo
      (:require ["ink" :refer [render Text]]
                [reagent.core :as r]))
    
    (defonce state (r/atom 0))
    
    (doseq [n (range 1 11)]
      (js/setTimeout #(swap! state inc) (* n 500)))
    
    (defn hello []
      [:> Text {:color "green"} "Hello, world! " @state])
    
    (render (r/as-element [hello]))

    Working with promises

    Promesa

    Working with callbacks and promises can become tedious. Since nbb v0.0.36 the promesa.core namespace is included with the let and do! macros. An example:

    (ns prom
      (:require [promesa.core :as p]))
    
    (defn sleep [ms]
      (js/Promise.
       (fn [resolve _]
         (js/setTimeout resolve ms))))
    
    (defn do-stuff
      []
      (p/do!
       (println "Doing stuff which takes a while")
       (sleep 1000)
       1))
    
    (p/let [a (do-stuff)
            b (inc a)
            c (do-stuff)
            d (+ b c)]
      (prn d))
    $ nbb prom.cljs
    Doing stuff which takes a while
    Doing stuff which takes a while
    3

    Also see API docs.

    REPL

    In the REPL it can be convenient to bind the resolved value of promises to a var. You can do that like this:

    (defmacro defp [binding expr]
      `(-> ~expr (.then (fn [val]
                         (def ~binding val)))))
    
    (defp browser (.launch puppeteer #js {:headless false}))
    (defp page (.newPage browser))
    (.goto page "https://clojure.org")

    Cljs-bean

    Since nbb v0.1.0 cljs-bean is available.

    See the example for an example.

    Js-interop

    Since nbb v0.0.75 applied-science/js-interop is available:

    (ns example
      (:require [applied-science.js-interop :as j]))
    
    (def o (j/lit {:a 1 :b 2 :c {:d 1}}))
    
    (prn (j/select-keys o [:a :b])) ;; #js {:a 1, :b 2}
    (prn (j/get-in o [:c :d])) ;; 1

    Most of this library is supported in nbb, except the following:

    • destructuring using :syms
    • property access using .-x notation. In nbb, you must use keywords.

    See the example of what is currently supported.

    Reader conditionals

    Nbb supports the following reader conditional features: :org.babashka/nbb and :cljs in that order of priority:

    #?(:org.babashka/nbb 1 :cljs 2) ;;=> 1
    #?(:cljs 2 :org.babashka/nbb 1) ;;=> 2

    REPL

    Console REPL

    To start a console REPL, simply run nbb.

    Socket REPL

    To start a socket server REPL, run:

    $ nbb socket-repl :port 1337

    REPL API

    Nbb exposes the nbb.repl namespace to programmatically start a REPL. See API for more info. An example:

    (ns example
      (:require [nbb.repl :as repl]
                [promesa.core :as p]))
    
    (defn available-in-repl [] :yolo)
    
    (p/do!
     (repl/repl)
     ;; type (available-in-repl) in the REPL and it will return :yolo
     (println "The end"))

    The repl function returns a promise. The promesa.core/do! macro waits for the REPL to finish and after that "The end" is printed:

    $ nbb example.cljs
    example=> (available-in-repl)
    :yolo
    example=> The end

    To launch a REPL from a Node.js script, you can use loadString or loadFile:

    import { loadString } from 'nbb'
    await loadString(`
    (require '[nbb.repl :refer [repl]])
    (repl)
    `)
    console.log('The end!')
    $ node repl.mjs
    user=> (+ 1 2 3)
    6
    user=> The end!

    nREPL

    The nREPL server probably still has rough edges. Please report issues here.

    An nREPL server can be started with:

    $ nbb nrepl-server :port 1337

    After that you can connect using an nREPL client:

    $ lein repl :connect 1337

    and evaluate expressions.

    Calva

    In Calva connect to the REPL with:

    • Connect to a Running REPL Server not in Project > ClojureScript nREPL server

    CIDER

    Currently CIDER needs the following workaround.

    Vim Iced

    See this tweet.

    Projects using nbb

    The following projects are using nbb or are supporting it as a development platform:

    Examples

    API

    See API documentation.

    Articles

    Migrating to shadow-cljs

    See this gist on how to convert an nbb script or project to shadow-cljs.

    Publishing an nbb project to npm

    See Publishing an nbb project to npm

    Build

    Prequisites:

    • babashka >= 0.4.0
    • Clojure CLI >= 1.10.3.933
    • Node.js 16.5.0 (lower version may work, but this is the one I used to build)

    To build:

    • Clone and cd into this repo
    • bb release

    Run bb tasks for more project-related tasks.

    Credits

    • Original babashka logo by Nikita Prokopov. Node.js modifications by MnRa.

    License

    Copyright © 2021 Michiel Borkent

    Distributed under the EPL License. See LICENSE.

    Keywords

    none

    Install

    npm i nbb

    DownloadsWeekly Downloads

    346

    Version

    0.1.1

    License

    EPL-1.0

    Unpacked Size

    1.87 MB

    Total Files

    19

    Last publish

    Collaborators

    • borkdude