feat: implement a command line interface (CLI)

Author: josdejong

README.md

@@ -25,6 +25,7 @@ On this page:
 - [Syntax](#syntax)
 - [JSON Format](#json-format)
 - [JavaScript API](#javascript-api)
+- [Command line interface (CLI)](#command-line-interface-cli)
 - [Gotchas](#gotchas)
 - [Development](#development)
 - [Motivation](#motivation)
@@ -566,6 +567,48 @@ try {
 }
 ```
 
+## Command line interface (CLI)
+
+When `jsonquery` is installed globally using npm, it can be used on the command line. To install `jsonquery` globally:
+
+```bash
+$ npm install -g @jsonquerylang/jsonquery
+```
+
+Usage:
+
+```
+$ jsonquery [query] {OPTIONS}
+```
+
+Options:
+
+```
+--input         Input file name
+--query         Query file name
+--output        Output file name
+--format        Can be "text" (default) or "json"
+--indentation   A string containing the desired indentation, 
+                like "  " (default) or "    " or "\t". An empty
+                string will create output without indentation.
+--overwrite     If true, output can overwrite an existing file
+--version, -v   Show application version
+--help,    -h   Show this message
+```
+
+Example usage:
+
+```
+$ jsonquery --input users.json 'sort(.age)'
+$ jsonquery --input users.json 'filter(.city == "Rotterdam") | sort(.age)'
+$ jsonquery --input users.json 'sort(.age)' > output.json
+$ jsonquery --input users.json 'sort(.age)' --output output.json
+$ jsonquery --input users.json --query query.txt
+$ jsonquery --input users.json --query query.json --format json
+$ cat users.json | jsonquery 'sort(.age)'
+$ cat users.json | jsonquery 'sort(.age)' > output.json
+```
+
 ## Gotchas
 
 The JSON Query language has some gotchas. What can be confusing at first is to understand how data is piped through the query. A traditional function call is for example `max(myValues)`, so you may expect to have to write this in JSON Query like `["max", "myValues"]`. However, JSON Query has a functional approach where we create a pipeline like: `data -> max -> result`. So, you will have to write a pipe which first gets this property and next calls the function max: `.myValues | max()`.

bin/cli.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { jsonquery } from '../lib/jsonquery.js'
+import { help } from './help.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const options = {
+  input: { type: 'string' },
+  query: { type: 'string' },
+  output: { type: 'string' },
+  format: { type: 'string', default: 'text' },
+  overwrite: { type: 'boolean', default: false },
+  indentation: { type: 'string', default: '  ' },
+  version: { type: 'boolean', short: 'v' },
+  help: { type: 'boolean', short: 'h' }
+}
+
+const {
+  values,
+  positionals: [inlineQuery]
+} = parseArgs({ options, allowPositionals: true })
+
+await run({ ...values, inlineQuery })
+
+/**
+ * @param {Options} options
+ * @returns {Promise<void>}
+ */
+async function run(options) {
+  if (options.version) {
+    return writeVersion()
+  }
+
+  if (options.help) {
+    return writeHelp()
+  }
+
+  try {
+    const input = await readInput(options)
+    const query = readQuery(options)
+
+    const output = jsonquery(input, query)
+
+    return writeOutput(options, output)
+  } catch (err) {
+    process.stderr.write(err.toString())
+    process.exit(1)
+  }
+}
+
+/**
+ * @param {Options} options
+ * @returns {Promise<string>}
+ */
+async function readInput(options) {
+  const inputStr = options.input ? fileToString(options.input) : await streamToString(process.stdin)
+
+  if (inputStr.trim() === '') {
+    throw Error('No input data provided')
+  }
+
+  return JSON.parse(inputStr)
+}
+
+/**
+ * @param {Options} options
+ * @returns {Promise<string>}
+ */
+function readQuery(options) {
+  const queryStr = options.query
+    ? fileToString(options.query)
+    : options.inlineQuery
+      ? options.inlineQuery
+      : throwError('No query provided')
+
+  return options.format === 'text' || options.format === undefined
+    ? queryStr
+    : options.format === 'json'
+      ? JSON.parse(queryStr)
+      : throwError(`Unknown format "${options.format}". Choose either "text" (default) or "json".`)
+}
+
+/**
+ * @param {Options} options
+ * @param {JSON} output
+ */
+function writeOutput(options, output) {
+  const outputStr = JSON.stringify(output, null, options.indentation)
+
+  if (options.output) {
+    if (existsSync(options.output) && !options.overwrite) {
+      throwError(`Cannot overwrite existing file "${options.output}"`)
+    }
+
+    writeFileSync(options.output, outputStr)
+  } else {
+    process.stdout.write(outputStr)
+  }
+}
+
+function writeVersion() {
+  const file = join(__dirname, '../package.json')
+  const pkg = JSON.parse(String(readFileSync(file, 'utf-8')))
+
+  process.stdout.write(pkg.version)
+}
+
+function writeHelp() {
+  process.stdout.write(help)
+}
+
+function fileToString(fileName) {
+  return String(readFileSync(fileName))
+}
+
+/**
+ * @param {ReadableStream} readableStream
+ * @returns {Promise<string>}
+ */
+function streamToString(readableStream) {
+  return new Promise((resolve, reject) => {
+    let text = ''
+
+    readableStream.on('data', (chunk) => {
+      text += String(chunk)
+    })
+    readableStream.on('end', () => {
+      readableStream.destroy()
+      resolve(text)
+    })
+    readableStream.on('error', (err) => reject(err))
+  })
+}
+
+function throwError(message) {
+  throw new Error(message)
+}
+
+/**
+ * @typedef {Object} Options
+ * @property {boolean} [version]
+ * @property {boolean} [help]
+ * @property {string} [input]
+ * @property {string} [query]
+ * @property {string} [output]
+ * @property {string} [inlineQuery]
+ * @property {'text' | 'json'} [format='text']
+ * @property {string} [indentation='  ']
+ * @property {boolean} [overwrite=false]
+ */

bin/help.js

@@ -0,0 +1,37 @@
+export const help = `
+jsonquery
+https://github.com/jsonquerylang/jsonquery
+
+Query JSON documents. The command line application requires an input document
+and query, and returns output containing the query result. The query can be
+either in text format (default) or json format.
+
+Usage:
+
+    jsonquery [query] {OPTIONS}
+
+Options:
+
+    --input         Input file name
+    --query         Query file name
+    --output        Output file name
+    --format        Can be "text" (default) or "json"
+    --indentation   A string containing the desired indentation, 
+                    like "  " (default) or "    " or "\\t". An empty
+                    string will create output without indentation.
+    --overwrite     If true, output can overwrite an existing file
+    --version, -v   Show application version
+    --help,    -h   Show this message
+
+Example usage:
+
+    jsonquery --input users.json 'sort(.age)'
+    jsonquery --input users.json 'filter(.city == "Rotterdam") | sort(.age)'
+    jsonquery --input users.json 'sort(.age)' > output.json
+    jsonquery --input users.json 'sort(.age)' --output output.json
+    jsonquery --input users.json --query query.txt
+    jsonquery --input users.json --query query.json --format json
+    cat users.json | jsonquery 'sort(.age)'
+    cat users.json | jsonquery 'sort(.age)' > output.json
+
+`

package.json

@@ -20,6 +20,9 @@
     "type": "git",
     "url": "git+https://github.com/jsonquerylang/jsonquery.git"
   },
+  "bin": {
+    "jsonquery": "./bin/cli.js"
+  },
   "module": "./lib/jsonquery.js",
   "types": "./lib/jsonquery.d.ts",
   "exports": {