npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@hoijnet/tuscli

v0.2.3

Published

TerminusDB Javascript CLI

Downloads

49

Readme

tuscli - Independent TerminusDB Javascript document cli

Note: Tuscli was previously hoijnet/tuscli and DFRNT assumed maintainership for it since 2023-01-21.

Interact with TerminusDB and DFRNT from the commandline to import/export documents and setup the schema.

This open source tool is built to help changemakers leverage semantic knowledge graphs from the command line. We, DFRNT, believe in data mesh as a great bearer of structured organisational data. We leverage TerminusDB to build our product on. This tuscli tooling integrates TerminusDB/TerminusX data and complements the DFRNT platform.

Sign up to the DFRNT waiting list to receive your invitation to our beta. We have slowly begun the onboarding now during early 2022.

Requirements unless using a prepackaged form

Usage

When running with docker and docker-compose, use the correct host, and add the docker network to connect run the command with.

$ export TUSPARAMS="$(echo '{"url":"http://localhost:6363","key":"password","user":"admin","organisation":"admin","db":"mydb"}' | base64 )"
$ docker run --rm -it --network terminusdb_default -e TUSPARAMS="$TUSPARAMS" hoijnet/tuscli --help
$ docker run --rm -it --network terminusdb_default -e TUSPARAMS="$TUSPARAMS" hoijnet/tuscli --export-schema
$ docker run --rm -it --network terminusdb_default -e TUSPARAMS="$TUSPARAMS" hoijnet/tuscli --query-document '{"type":"Person"}'
$ docker run --rm -it --network terminusdb_default -e TUSPARAMS="$TUSPARAMS" hoijnet/tuscli --read Person/johndoe
$ docker run --rm -it --network terminusdb_default -e TUSPARAMS="$TUSPARAMS" hoijnet/tuscli --delete Person/johndoe
$ docker run --rm -it --network terminusdb_default -e TUSPARAMS="$TUSPARAMS" hoijnet/tuscli --instance schema --read Person

Interact with TerminusDB from the commandline to import/export documents and setup the schema.

$ export TUSPARAMS="$(echo '{"url":"http://localhost:6363","key":"password","user":"admin","organisation":"admin","db":"mydb"}' | base64 )"
$ npm install
$ node dist/tuscli.js

Build a docker image with tuscli as a binary in it, note that nexe itself takes a long time to compile.

$ docker build --pull -t tuscli -f docker/Dockerfile .
$ docker run --rm -it tuscli --help
$ echo '{ "@id": "newenum", "@type": "Enum", "@value": [ "mytest" ] }' > examples/newenum.json
$ docker run --rm -it -e TUSPARAMS="$TUSPARAMS" -v "`pwd`"/examples:/json tuscli -i schema -c /json/newenum.json

To build an executable tuscli file with embedded node.js in it:

$ npm run buildnexe
$ ./tuscli --help

Install tuscli globally on your system

$ sudo npm install -g @hoijnet/tuscli

Examples

$ node dist/tuscli.js --createBranch mybranch true
$ node dist/tuscli.js --branch mybranch --export-schema
$ node dist/tuscli.js --query-document '{"type":"Person"}'
$ node dist/tuscli.js --read Person/johndoe
$ node dist/tuscli.js --delete Person/johndoe
$ node dist/tuscli.js --instance schema --create "`pwd`/schemaDocument.json"
$ node run buildnexe
$ ./tuscli --instance schema --update Person ./person.json

To import and export, make sure that the coloring is removed from the json, and remove the TerminusDB schema preamble. Then it is possible to import the JSON array of documents with --instance schemaand --create flags. Can be helpful to try in a separate branch as well.

Additional examples can be found in the examples folder, including an example of CSV document import using WOQL.

Motivation and Features

  • Load documents into TerminusDB from the cli
  • Interact with schema, system and instance parts of TerminusDB from the cli
  • It was easier for me to get started in Javascript 😄
  • Consider using the official TerminusDB Python scaffolding cli instead, one that has these and more advanced features!

Project goals

  • Make it easy to import/export schema/system/instance TerminusDB documents to/from disk
  • Make it easy to interact with TerminusDB from the command line
  • Show simple usage of the Javascript TermimusDB SDK
  • Enable interaction with other on-disk JSON manipulation tools
  • Easy of use, stability and correctness to be a higher priority than many features

tuscli options

Usage: tuscli [options]

TerminusDB Javascript cli: tuscli [options] <fileName(s)>

Options:
  -V, --version                                    output the version number
  -c, --create                                     create document from provided file
  --createFromJson                                 create document from supplied JSON, like '{"@id":"Entity/1",
                                                   "@type":"Entity"}'
  -r, --read <document-id>                         read document-id (Type/id)
  -s, --schemaFrame <document-id>                  get the schema frame for a type/subdoctype/enum
  -u, --update <document-id>                       update document
  -d, --delete <document-id>                       delete document
  -q, --query-documents <query-template-json>      list documents of type, example: {"type":"Person"}
  -e, --export-schema                              export/show instance schema JSON
  -p, --profile <json-file>                        JSON-formatted connection profile, or set env TUSPARAMS in base64
                                                   encoding
  -z, --dump-profile                               show the default or current connection profile, and how to set it
  -o, --optimize <main>                            optimize and do delta rollups on a branch
  --createDatabase <dataproduct-id> <create-json>  create data product, default JSON: {"schema":true, "label": "",
                                                   "comment":""}
  --deleteDatabase <dataproduct-id>                delete database/data product
  --deleteDocumentsOfType <type>                   delete all documents of a type
  --deleteDocumentsIsaType <type>                  delete documents that are is-a type
  --dataProduct <dataproduct-id>                   override dataproduct to use
  --createBranch <branch-id> <true/false>          create branch, true for empty branch
  --deleteBranch <branch-id>                       delete branch
  --branches                                       pull list of branches in the data product
  --nocolor                                        disable the colorize filter of output
  --quiet                                          disable diagnostic outputs
  -x, --system                                     connect to system database
  -y, --commitGraph <count>                        get the 10 last commits, supply an argument for more
  -i, --instance <instance|schema>                 document instance, default is instance
  -b, --branch <branch-id>                         use/select active branch
  -t, --commit <commit-id>                         use/select specific commit
  --woql <WOQL>                                    Execute JS WOQL query (as an argument)
  --compileWoql <WOQL>                             Compile JS WOQL (as an argument) into JSON WOQL
  --woqlFile <example.woql.js>                     Execute JS WOQL (from a file)
  --woqlCompile <example.woql.js>                  Compile JS WOQL into JSON WOQL (from a file)
  -h, --help                                       display help for command

Contributing

This is an independent single-contributor project (so far) done in my free time so issues may take time to get resolved (pull requests get issues resolved the fastest).

What needs help

  • Identify missing features and file issues
  • Usability/naming of the cli user interface (early feedback)
  • Usage examples (scripts with documents)
  • Make it more robust, this is an early version!

Howto release new version and ensure all builds work first

To put into a Makefile at some point

# Bump version number in package.json
$ npm run buildnexe
$ npm run dockerize
$ git push
$ npm push
$ docker push hoijnet/tuscli

How to build a self-contained command line binary with bun

bun build ./src/tuscli.ts --compile --outfile tuscli

Dependencies and mentions

  • Thanks to the great folks at TerminusDB for exciting open source technology
  • Thanks to debug used for debug output
  • Thanks to commander used for options parsing