logseq/nbb-logseq

Description

For Logseq users

nbb-logseq provides easy CLJS scripting on Node.js for Logseq. Since logseq is primarily written with ClojureScript, this scripting environment has capabilities that are not possible in any other environment. For example, see here for a script that queries any logseq graph.

For Clojure users

nbb-logseq is a custom version of nbb that bundles support for datascript, datascript-transit and a couple other cljs libraries that are useful to logseq. A good amount of the datascript API is available as seen by its tests. Since nbb only loads features/libraries when they are required, users can write datascript based CLIs without concern of loading the other libraries.

Usage

Install nbb-logseq from npm:

npm install @logseq/nbb-logseq -g

Omit -g for a local install.

All the usage examples from https://github.com/babashka/nbb#usage apply to nbb-logseq e.g.

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

Dependency Management

nbb-logseq can use libraries from both NPM and ClojureScript. For NPM libraries, use package.json like you would in a Node.js project. For ClojureScript libraries, create a nbb.edn file and install babashka. The two main keys a nbb.edn file supports are :deps and :paths. See babashka docs for more about the format of this file and those keys. See nbb's docs for more info about how nbb's dependencies generally work.

Logseq as a Dependency

Logseq's graph parser is a ClojureScript library with npm dependencies. To use it as a dependency requires a nbb.edn for the ClojureScript code and a package.json for the npm dependencies. For a quickstart with these files, copy them from the fly.io example. Note that Logseq code is fetched via git with nbb.edn so a specific commit and git repository can be specified.

Projects using nbb-logseq

• https://github.com/logseq/graph-validator - github action to validate graph
• https://github.com/cldwalker/logseq-query - commandline tool
• https://github.com/logseq/bb-tasks#logseqbb-tasksnbb - bb tasks that use nbb-logseq
• https://github.com/dom8509/logseq-to-markdown - CLI to export graph to Hugo Markdown files
• https://github.com/logseq/docs/tree/master/script - Scripts to query docs
• https://github.com/logseq/rdf-export - github action to export graph to RDF
• For more examples see the examples directory.

CLIs

Starting with version 1.2.168, nbb-logseq supports publishing node CLIs with a nbb.edn. This means that it's possible to write a script that uses logseq's graph-parser and share it with others so they can install it on their $PATH.

Community CLIs with a nbb.edn:

• logseq-graph-ast - CLI to print graph's ast data
• logseq-graph-validator - CLI to run validations on the current graph
• logseq-rdf-export - CLI to export graph as RDF
• https://github.com/cldwalker/logseq-clis - Collection of CLIs to run on graphs
• nbb-logseq-test-runner - CLI that runs cljs.test tests for a nbb compatible project
• logseq-publish-spa - CLI that publishes a graph as a single page app

To install or build a CLI locally, install babashka and clojure.

Install a CLI

From any script directory that has a nbb.edn, install CLIs on $PATH with yarn global add $PWD or npm i -g. If using yarn and ~/.yarn/bin is not on $PATH, add it to your shell's rc file e.g. export PATH="$HOME/.yarn/bin:$PATH".

Build a CLI

To convert a nbb-logseq cljs script into a CLI that others can install and use:

• Create a wrapper .mjs file that invokes your nbb-logseq cljs script.
  • Copy the graph_ast.mjs example and change the cljs file inside it.
• Add a bin entry to package.json that maps your CLI name to the cljs file.

For a tutorial on doing the above, read nbb's publish doc.

Versioning

nbb-logseq follows the same versioning as nbb. In other words, an 0.4.0 for nbb-logseq provides nbb 0.4.0 with the additional libraries.

Contributing

Example contributions are welcome. For feature contributions, please discuss them first as this is a low level library that will be relied on by multiple CLIs.

LICENSE

See LICENSE.md

Development

These sections for those developing this project.

QA local branch

To QA that your branch works as expected on a dependent repository e.g. logseq/graph-parser:

• bb release in this repo to build a local release.
• yarn add /path/to/nbb-logseq in a dependent's repo.
• Run yarn nbb-logseq FILE.cljs to run a given file. The graph-parser can confirm all it's namespaces load nbb-logseq with bb test:load-all-namespaces-with-nbb.

Release process

Steps to publish a new npm package:

1. Update CHANGELOG.md if anything specific to nbb-logseq has been updated.
2. Update nbb with bb update-nbb on https://github.com/babashka/nbb-features and confirm CI passes.

• This is done to confirm that datascript and datascript-transit tests pass.

3. Update nbb with bb update-nbb on this repo and confirm CI passes.

• This is done to run the test suite passes which includes cljs-time tests.

4. Run bb publish X.Y.Z where X.Y.Z is the version to publish. Push to github to publish.