jsonata

README

JSONata in Go

Package jsonata is a query and transformation language for JSON. It's a Go port of the JavaScript library JSONata.

It currently has feature parity with jsonata-js 1.5.4. As well as a most of the functions added in newer versions. You can see potentially missing functions by looking at the jsonata-js changelog.

Install

go get github.com/xiatechs/jsonata-go

Usage

import (
	"github.com/goccy/go-json"
	"fmt"
	"log"

	jsonata "github.com/xiatechs/jsonata-go"
)

const jsonString = `
    {
        "orders": [
            {"price": 10, "quantity": 3},
            {"price": 0.5, "quantity": 10},
            {"price": 100, "quantity": 1}
        ]
    }
`

func main() {

	var data interface{}

	// Decode JSON.
	err := json.Unmarshal([]byte(jsonString), &data)
	if err != nil {
		log.Fatal(err)
	}

	// Create expression.
	e := jsonata.MustCompile("$sum(orders.(price*quantity))")

	// Evaluate.
	res, err := e.Eval(data)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(res)
	// Output: 135
}

JSONata Server

A locally hosted version of JSONata Exerciser for testing is available here.

JSONata tests

A CLI tool for running jsonata-go against the JSONata test suite is available here.

Contributing

We love issues, fixes, and pull requests from everyone. Please run the unit-tests, staticcheck, and goimports prior to submitting your PR. By participating in this project, you agree to abide by the Blues Inc code of conduct.

For details on contributions we accept and the process for contributing, see our contribution guide.

In addition to the Go unit tests there is also a test runner that will run against the jsonata-js test suite in the jsonata-test directory. A number of these tests currently fail, but we're working towards feature parity with the jsonata-js reference implementation. Pull requests welcome!

If you would like to contribute to this library a good first issue would be to run the jsonata-test suite, and fix any of the tests not passing.

Documentation

Overview

Package jsonata is a query and transformation language for JSON. It's a Go port of the JavaScript library JSONata. Please use the official JSONata site as a language reference.

http://jsonata.org/

Index

• Variables
• func RegisterExts(exts map[string]Extension) error
• func RegisterVars(vars map[string]interface{}) error
• func RunEval(initialContext reflect.Value, expression ...interface{}) (interface{}, error)
• type ArgCountError
  • func (e ArgCountError) Error() string
• type ArgTypeError
  • func (e ArgTypeError) Error() string
• type ErrType
• type EvalError
  • func (e EvalError) Error() string
• type Expr
  • func Compile(expr string) (*Expr, error)
  • func MustCompile(expr string) *Expr
  • func (e *Expr) Eval(data interface{}) (interface{}, error)
  • func (e *Expr) EvalBytes(data []byte) ([]byte, error)
  • func (e *Expr) RegisterExts(exts map[string]Extension) error
  • func (e *Expr) RegisterVars(vars map[string]interface{}) error
  • func (e *Expr) String() string
• type Extension
• type JsonataProcessor
  • func NewProcessor(jsonataString string) (j *JsonataProcessor, err error)
  • func (j *JsonataProcessor) Execute(input interface{}) (output []map[string]interface{}, err error)

Examples

• Expr.Eval
• Expr.RegisterExts

Variables

var ErrUndefined = errors.New("no results found")

ErrUndefined is returned by the evaluation methods when a JSONata expression yields no results. Unlike most errors, ErrUndefined does not mean that evaluation failed.

The simplest way to trigger ErrUndefined is to look up a field that is not present in the JSON data. Many JSONata operators and functions also return ErrUndefined when called with undefined inputs.

Functions

func RegisterExts

func RegisterExts(exts map[string]Extension) error

RegisterExts registers custom functions for use in JSONata expressions. It is designed to be called once on program startup (e.g. from an init function).

Custom functions registered at the package level will be available to all Expr objects. To register custom functions with specific Expr objects, use the RegisterExts method.

func RegisterVars

func RegisterVars(vars map[string]interface{}) error

RegisterVars registers custom variables for use in JSONata expressions. It is designed to be called once on program startup (e.g. from an init function).

Custom variables registered at the package level will be available to all Expr objects. To register custom variables with specific Expr objects, use the RegisterVars method.

func RunEval

func RunEval(initialContext reflect.Value, expression ...interface{}) (interface{}, error)

Types

type ArgCountError

type ArgCountError struct {
	Func     string
	Expected int
	Received int
}

ArgCountError is returned by the evaluation methods when an expression contains a function call with the wrong number of arguments.

func (ArgCountError) Error

func (e ArgCountError) Error() string

type ArgTypeError

type ArgTypeError struct {
	Func      string
	Which     int
	Pos       int
	Arguments string
}

ArgTypeError is returned by the evaluation methods when an expression contains a function call with the wrong argument type.

func (ArgTypeError) Error

func (e ArgTypeError) Error() string

type ErrType

type ErrType uint

ErrType indicates the reason for an error.

const (
	ErrNonIntegerLHS ErrType = iota
	ErrNonIntegerRHS
	ErrNonNumberLHS
	ErrNonNumberRHS
	ErrNonComparableLHS
	ErrNonComparableRHS
	ErrTypeMismatch
	ErrNonCallable
	ErrNonCallableApply
	ErrNonCallablePartial
	ErrNumberInf
	ErrNumberNaN
	ErrMaxRangeItems
	ErrIllegalKey
	ErrDuplicateKey
	ErrClone
	ErrIllegalUpdate
	ErrIllegalDelete
	ErrNonSortable
	ErrSortMismatch
)

Types of errors that may be encountered by JSONata.

type EvalError

type EvalError struct {
	Type      ErrType
	Token     string
	Value     string
	Pos       int
	Arguments string
}

An EvalError represents an error during evaluation of a JSONata expression.

func (EvalError) Error

func (e EvalError) Error() string

type Expr

type Expr struct {
	// contains filtered or unexported fields
}

An Expr represents a JSONata expression.

func Compile

func Compile(expr string) (*Expr, error)

Compile parses a JSONata expression and returns an Expr that can be evaluated against JSON data. If the input is not a valid JSONata expression, Compile returns an error of type jparse.Error.

func MustCompile

func MustCompile(expr string) *Expr

MustCompile is like Compile except it panics if given an invalid expression.

func (*Expr) Eval

func (e *Expr) Eval(data interface{}) (interface{}, error)

Eval executes a JSONata expression against the given data source. The input is typically the result of unmarshaling a JSON string. The output is an object suitable for marshaling into a JSON string. Use EvalBytes to skip the unmarshal/marshal steps and work solely with JSON strings.

Eval can be called multiple times, with different input data if required.

Example

package main

import (
	"fmt"
	"github.com/goccy/go-json"
	"log"

	jsonata "github.com/xiatechs/jsonata-go"
)

const jsonString = `
    {
        "orders": [
            {"price": 10, "quantity": 3},
            {"price": 0.5, "quantity": 10},
            {"price": 100, "quantity": 1}
        ]
    }
`

func main() {

	var data interface{}

	// Decode JSON.
	err := json.Unmarshal([]byte(jsonString), &data)
	if err != nil {
		log.Fatal(err)
	}

	// Create expression.
	e := jsonata.MustCompile("$sum(orders.(price*quantity))")

	// Evaluate.
	res, err := e.Eval(data)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(res)
}

Output:

135

func (*Expr) EvalBytes

func (e *Expr) EvalBytes(data []byte) ([]byte, error)

EvalBytes is like Eval but it accepts and returns byte slices instead of objects.

func (*Expr) RegisterExts

func (e *Expr) RegisterExts(exts map[string]Extension) error

RegisterExts registers custom functions for use during evaluation. Custom functions registered with this method are only available to this Expr object. To make custom functions available to all Expr objects, use the package level RegisterExts function.

Example

package main

import (
	"fmt"
	"log"
	"strings"

	jsonata "github.com/xiatechs/jsonata-go"
)

//
// This example demonstrates how to extend JSONata with
// custom functions.
//

// exts defines a function named "titlecase" which maps to
// the standard library function strings.Title. Any function,
// from the standard library or otherwise, can be used to
// extend JSONata, as long as it returns either one or two
// arguments (the second argument must be an error).
var exts = map[string]jsonata.Extension{
	"titlecase": {
		Func: strings.Title,
	},
}

func main() {

	// Create an expression that uses the titlecase function.
	e := jsonata.MustCompile(`$titlecase("beneath the underdog")`)

	// Register the titlecase function.
	err := e.RegisterExts(exts)
	if err != nil {
		log.Fatal(err)
	}

	// Evaluate.
	res, err := e.Eval(nil)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(res)
}

Output:

Beneath The Underdog

func (*Expr) RegisterVars

func (e *Expr) RegisterVars(vars map[string]interface{}) error

RegisterVars registers custom variables for use during evaluation. Custom variables registered with this method are only available to this Expr object. To make custom variables available to all Expr objects, use the package level RegisterVars function.

func (*Expr) String

func (e *Expr) String() string

String returns a string representation of an Expr.

type Extension

type Extension struct {

	// Func is a Go function that implements the custom
	// functionality and returns either one or two values.
	// The second return value, if provided, must be an
	// error.
	Func interface{}

	// UndefinedHandler is a function that determines how
	// this extension handles undefined arguments. If
	// UndefinedHandler is non-nil, it is called before
	// Func with the same arguments. If the handler returns
	// true, Func is not called and undefined is returned
	// instead.
	UndefinedHandler jtypes.ArgHandler

	// EvalContextHandler is a function that determines how
	// this extension handles missing arguments. If
	// EvalContextHandler is non-nil, it is called before
	// Func with the same arguments. If the handler returns
	// true, the evaluation context is inserted as the first
	// argument when Func is called.
	EvalContextHandler jtypes.ArgHandler
}

An Extension describes custom functionality added to a JSONata expression.

type JsonataProcessor

type JsonataProcessor struct {
	// contains filtered or unexported fields
}

func NewProcessor

func NewProcessor(jsonataString string) (j *JsonataProcessor, err error)

func (*JsonataProcessor) Execute

func (j *JsonataProcessor) Execute(input interface{}) (output []map[string]interface{}, err error)

Execute - helper function that lets you parse and run jsonata scripts against an object