fx

What is fx?

The fx npm package is a command-line JSON processing tool that allows users to manipulate and transform JSON data using JavaScript expressions. It is designed to be simple and powerful, enabling quick and efficient JSON data processing directly from the terminal.

What are fx's main functionalities?

Basic JSON Filtering

This feature allows you to filter JSON data to extract specific fields. In this example, the command extracts the 'name' field from the JSON object.

echo '{"name": "John", "age": 30}' | fx '.name'

Complex JSON Transformations

This feature enables complex transformations of JSON data using JavaScript functions. The example command maps over an array of objects and extracts the 'name' field from each object.

echo '[{"name": "John", "age": 30}, {"name": "Jane", "age": 25}]' | fx 'map(x => x.name)'

Chaining Operations

This feature allows chaining multiple operations to perform more complex data manipulations. The example command filters the array to include only objects where 'age' is greater than 25 and then maps to extract the 'name' field.

echo '[{"name": "John", "age": 30}, {"name": "Jane", "age": 25}]' | fx 'filter(x => x.age > 25).map(x => x.name)'

Other packages similar to fx

jq

jq is a lightweight and flexible command-line JSON processor. It allows for powerful data manipulation and transformation using its own domain-specific language. Compared to fx, jq is more feature-rich and has a steeper learning curve due to its unique syntax.

json

The json command-line tool is a simpler alternative for working with JSON data. It allows for basic filtering and transformation using JavaScript expressions. While it is less powerful than fx, it is easier to use for straightforward tasks.

jshon

jshon is another command-line tool for JSON manipulation. It provides a set of commands for extracting and transforming JSON data. Compared to fx, jshon is more Unix-like and script-friendly but may require more verbose commands for complex operations.

README

fx

A non-interactive, JavaScript version of the fx. Short for Function eXecution or f(x).

npm i -g fx

Or use npx:

cat file.json | npx fx .field

Or use deno:

cat file.json | deno run -A npm:fx .field

Usage

Fx treats arguments as JavaScript functions. Fx passes the input data to the first function and then passes the result of the first function to the second function and so on.

echo '{"name": "world"}' | fx 'x => x.name' 'x => `Hello, ${x}!`'

Use this to access the input data. Use . at the start of the expression to access the input data without a x => x part.

echo '{"name": "world"}' | fx '.name' '`Hello, ${this}!`'

Use other JS functions to process the data.

echo '{"name": "world"}' | fx 'Object.keys'

Stream processing

Fx can process a stream of json objects. Fx will apply arguments to each object.

echo '{"name": "hello"}\n{"name": "world"}' | fx '.name'

If you want to process a stream of json objects as a single array, use the --slurp or -s flag.

echo '{"name": "hello"}\n{"name": "world"}' | fx --slurp '.map(x => x.name)' '.join(", ")'

Raw input

If you want to process non-JSON data, use the --raw or -r flag.

ls | fx -r '[this, this.includes(".md")]'

You can use --raw and --slurp (or -rs) together to get a single array of strings.

ls | fx -rs '.filter(x => x.includes(".md"))'

Fx has a special symbol skip for skipping the printing of the result.

ls | fx -r '.includes(".md") ? this : skip'

Built-in functions

Fx comes with a set of useful functions: uniq, sort, groupBy, chunk, zip.

cat file.json | fx 'uniq' 'sort' 'groupBy(x => x.name)'

Edit-in-place

You can use special function save to edit-in-place the input data.

fx file.json 'x.name = x.name.toUpperCase(), x' 'save'

The edited data will be saved to the same file.json file.

Syntactic Sugar

Fx has a shortcut for the map function. Fox example, this.map(x => x.commit.message) can be rewritten without leading dot and without x => x parts.

curl https://api.github.com/repos/antonmedv/fx/commits | fx 'map(.commit.message)'

echo '[{"name": "world"}]' | fx 'map(`Hello, ${x.name}!`)'

Fx has a special syntax for the flatMap function. Fox example, .issues.flatMap(x => x.labels.flatMap(x => x)) can be rewritten in the next way.

curl https://fx.wtf/example.json | fx '.issues[].labels[]'

.fxrc.js

Fx supports .fxrc.js file in the current directory, or in the home directory, or in XDG config directory.

Put the next code in the .fxrc.js file to make myFunction available in the fx.

function addOne(x) {
  return x + 1
}

Now you can use addOne in the fx.

echo '1' | fx addOne

If you would like to create global variables use var instead of let or const.

License

MIT