jsonata.node.txt

                                  ┏━━━━━━━━━━━━━┓
                                  ┃   JSONATA   ┃
                                  ┗━━━━━━━━━━━━━┛

ALTERNATIVES ==>                  #  - jsonata (preferred)
                                  #     - more features
                                  #     - high profile
                                  #     - well maintained
                                  #     - templating
                                  #  - jq:
                                  #     - similar to jsonata
                                  #     - most features
                                  #     - highest profile
                                  #     - not documented yet
                                  #  - JMESPath
                                  #     - not well maintained, except for Powertools Lambda implementation
                                  #     - mostly only used by AWS
                                  #     - more features: && or || chaining, more flexible transforms, and builtin functions
                                  #     - templating
                                  #  - JSONPath
                                  #     - not well maintained
                                  #     - simpler
                                  #     - read-only
                                  #  - wild-wild-path (preferred if read/write)
                                  #     - maintained by me
                                  #     - simplest: REGEXP instead of imperative filters
                                  #     - read/write
                                  #     - has functional utilities
                                  #     - either STR or OBJ syntax
                                  #     - more powerfull ** (leaf|root-only, recursion order, recurse on ARR|CLASS or not)


VERSION ==>                       #2.0.6

VSCODE EXTENSION ==>              #Exists

@stedi/
 prettier-plugin-jsonata prettier #Prettier plugin

                                  ┌──────────────────┐
                                  │   PROGRAMMATIC   │
                                  └──────────────────┘

jsonata                           #Node/browser

JSONATA('QUERY'[, OPTS])->QUERY   #
OPTS.recover                      #BOOL. If false (def), throws on syntax ERROR
                                  #If true, sets QUERY.errors()->ERROR_ARR

QUERY.evaluate(VAL)->>VAL2        #Evaluates QUERY using VAL as $$
                                  #Can throw, e.g. on unknown $FUNC or invalid $FUNC() arguments
                                  #If no match, returns undefined (no ERROR)

ERROR                             #Has message|stack properties, but not an actual ERROR instance
ERROR.code                        #'CODE'
ERROR.position                    #NUM
ERROR.token                       #STR
ERROR.value                       #STR|undefined

QUERY.ast()->OBJ                  #Parse tree, i.e. AST (not documented yet)

                                  ┌─────────┐
                                  │   CLI   │
                                  └─────────┘

ALTERNATIVES ==>                  #  - jfq (preferred)
                                  #     - more features
                                  #     - better maintained
                                  #     - more high profile
                                  #  - jsonata-cli

VERSION ==>                       #1.2.11

jfq ['QUERY'] [PATH...]           #Evaluates QUERY and print its result
                                  #Def QUERY: '$'
                                  #$ value is PATH (def: stdin), as JSON
                                  #If multiple PATHs, each is evaluated and its result printed.

--query-file|-q                   #PATH to QUERY, instead of passing as positional argument

--accept-yaml|-a                  #Use YAML as $ value instead

--json|-j                         #Unless set, if result is:
                                  #  - STR: printed as is (not JSON)
                                  #  - STR_ARR|NUM_ARR: printed as newline-separated list (not JSON)
--ndjson|-n                       #Output each JSON VAL:
                                  #  - on a single line
                                  #  - instead of multiple lines (prettified)
--yaml|-y                         #Output as YAML
--plain-text|-p                   #No colors

                                  ┌─────────────┐
                                  │   CONTEXT   │
                                  └─────────────┘

$                                 #Context

VAL.(...)
VAL.{...}
VAL.[...]
OBJ....
| ... | ... |
ARR[...]
ARR^(...)                         #$ in ... in the value from the left hand

VAL.(...)                         #Like ... but using VAL as $

{...}                             #$ stays same inside ... (literal VAL)
[...]                             #E.g. $ and {"VAR": [$]} use the same value for $

IMPLICIT CONTEXT                  #If EXPR does not start with $, it is implicit
                                  #E.g. VAR -> $.VAR or `VAR` -> $.`VAR`
                                  #Not for $[...] since it is ambiguous with literal ARR [...]

%                                 #Parent context
%.%                               #Grandparent context (and so on)

$$                                #Initial|root context

                                  ┌────────────────┐
                                  │   EXPRESSION   │
                                  └────────────────┘

TYPES ==>                         #JSON types + FUNC

undefined                         #Omitted in OBJ and ARR

null|BOOL|NUM|STR|OBJ|ARR         #Literal values
                                  #Same format as JSON
                                  #I.e. JSONata is superset of JSON
'...'                             #Literal value. Same as "..." except must escape " instead of '

EXPR                              #Any of the operators and $FUNC() below
                                  #Can be inside a literal value, allowing templating
                                  #  - e.g. {"VAR": EXPR, ...}

VAL                               #Any value documented here is either:
                                  #  - literal JSON value (or '...'): if follows syntax
                                  #  - EXPR: else
                                  #E.g.:
                                  #  - {...}.{"VAR": EXPR, ...} vs OBJ_EXPR.{VAR_EXPR: "VAL", ...}
                                  #  - ARR[BOOL_EXPR]
                                  #  - OBJ.(EXPR)
                                  #For OBJ keys: literal if 'VAR' or "VAR", EXPR if unquoted
                                  #  - can mix both, e.g. {"VAR": VAL, EXPR: VAL2}

                                  ┌───────────────┐
                                  │   ITERATION   │
                                  └───────────────┘

ARR.$FUNC(...)                    #Maps ARR items with FUNC
                                  #Except if FUNC's argument is expected to be an ARR
ARR....                           #Same with any dot-separated operator: ARR.VAR, ARR.(...), ARR.{...}, ARR.[...], etc.
                                  #E.g. OBJ_ARR.VAR -> [OBJ.VAR, OBJ2.VAR, ...]
$FUNC(ARR, ...)
$.[ARR].$FUNC(...)
$.[ARR]...                        #Prevents iteration, i.e. use a whole

$FUNC(VAL, ...)                   #If FUNC expects an ARR, but VAL is not an ARR, converts it to [VAL]
VAL[...]
VAL^(...)
VAL{...}                          #Same with operators that expect ARRs

EMPTY ARRAY ==>                   #If FUNC|operator returns a top-level ARR with no items, it is converted to undefined instead
[VAL]                             #Prevents that conversion, since it is not applied to literal ARRs, and undefined are omitted

SINGLE ITEM ==>                   #If FUNC|operator returns a top-level ARR with a single item, it is converted to non-ARR instead
VAL[]                             #Prevents that conversion

OBJ_ARR.$FUNC(...)                #If $FUNC(OBJ)->ARR, flattens
ARR.(...)
OBJ_ARR.VAR
OBJ_ARR.`VAR`
OBJ_ARR.*
OBJ_ARR.**                        #Same with any dot-separated operator returning an ARR
ARR[...]
ARR.[...]                         #Not flattened. E.g. can be used to prevent flattening: OBJ_ARR.[$FUNC(...)], ARR.[(...)], etc.

                                  ┌────────────────┐
                                  │   STATEMENTS   │
                                  └────────────────┘

/* COMMENT */                     #Can be inline

(VAL)                             #Operator precedence
                                  #Order is . [] ^ # @

(VAL;...)                         #Evaluates all VALs, returns last one
                                  #I.e. meant for multiple statements, e.g.:
                                  #  - inside a FUNC body
                                  #  - $VAR assignment

BOOL ? VAL : VAL2                 #Implicitely typecast (using $boolean())

$error('MESSAGE')                 #Throws ERROR
$assert(BOOL, 'MESSAGE')          #BOOL ? undefined : $error('MESSAGE')

$eval('QUERY'[, $$])->VAL         #Evaluate JSONata inside JSONata itself
                                  #Since JSONata is superset of JSON, can JSON parse too
                                  #Def $$: current $

                                  ┌───────────────────┐
                                  │   FUNCTION CALL   │
                                  └───────────────────┘

$FUNC(...)                        #Calls FUNC

VAL.$FUNC(...)                    #Same as $FUNC(VAL, ...)
                                  #Possible with every built-in FUNC|operator
                                  #Not possible when VAL is ARR
                                  #  - since it is ambiguous with ARR mapping
                                  #Not possible when next argument is passed and it has same type (or subtype) as VAL
                                  #  - since it is ambiguous
                                  #  - e.g. NUM.$round(NUM2) or STR.$string(true) (since true is typecastable to STR)
(VAL).$FUNC(...)                  #Must be used if VAL is literal VAL (except OBJ)

$FUNC(..., ?, ...)->FUNC2         #Bind other arguments

VAL ~> $FUNC[(...)]               #Same as $FUNC(VAL, ...)
VAL ~> $FUNC ~> $FUNC2[(...)]     #Same as $FUNC2($FUNC(VAL, ...))
$FUNC ~> $FUNC2                   #Same as function(...) { $FUNC2($FUNC(...), ...) }

                                  ┌─────────────────────┐
                                  │   FUNCTION DEFINE   │
                                  └─────────────────────┘

function($ARG,...) { VAL }        #FUNC
                                  #No ; after VAL
                                  #Can be called as anonymous FUNC
                                  #Uses lexical scoping and closure, i.e. can use outer scope's $VAR, including $
                                  #Can be recursive
                                  #Can use tail call optimization

$VAR := FUNC
FUNC(FUNC2, ...)                  #FUNCs are values

QUERY.registerFunction
 ('FUNC', FUNC[, '<TYPES>'])      #Define $FUNC using JavaScript FUNC

                                  ┌────────────────────┐
                                  │   FUNCTION TYPES   │
                                  └────────────────────┘

function(...) <TYPES> { ... }     #Validates input of FUNC. Optional
                                  #<TYPES> is <T...:T>
                                  #Each T in left part (concatenated) is ARG type
                                  #Last T is return type
                                  #E.g. <a(an):n>
                                  #T is any of the following

l                                 #null
b                                 #BOOL
n                                 #NUM
s                                 #STR
a                                 #ARR
a<T>                              #ARR of T
o                                 #OBJ
f                                 #FUNC
f<TYPES>                          #FUNC with specific signature

u                                 #null|BOOL|NUM|STR
j                                 #null|BOOL|NUM|STR|ARR|OBJ
x                                 #null|BOOL|NUM|STR|ARR|OBJ|FUNC

(T...)                            #Union (or)
T?                                #Optional
T+                                #Variadic (>=1)
T-                                #Allows VAL.$FUNC(...) with VAL being this argument

                                  ┌───────────────┐
                                  │   VARIABLES   │
                                  └───────────────┘

$VAR := VAL                       #Assignment

QUERY.assign('VAR', VAL)
QUERY.evaluate
 (..., {VAR: VAL, ...})           #Assignment from JavaScript

$ := VAL                          #Noop
$$ := VAL                         #Possible (but should not do it)

$VAR                              #Referencing
                                  #If unknown: undefined (no ERROR)

(...)                             #$VAR scope
OBJ.(...)                         #Can access parent scopes
function (...) { ... }            #Can set parent scopes, but only shadows them

ARR@$VAR                          #Assigns $VAR with the ARR current iteration's item VAL
ARR#$VAR                          #Same with item's index

                                  ┌──────────┐
                                  │   TYPE   │
                                  └──────────┘

$type(VAL)[->STR]                 #'null|number|string|boolean|array|object|function' or undefined

$exists(VAL)->BOOL                #Not undefined

                                  ┌───────────┐
                                  │   EQUAL   │
                                  └───────────┘

VAL = != VAL2                     #Deep equal
                                  #OBJ keys order not significant, but ARR order significant

BOOL|NUM|STR|null in ARR          #BOOL2

                                  ┌─────────────┐
                                  │   BOOLEAN   │
                                  └─────────────┘

VAL.$boolean()->BOOL              #Typecast. false if:
                                  #  - null
                                  #  - 0
                                  #  - empty STR
                                  #  - empty OBJ
                                  #  - ARR empty, or with only falsy values
                                  #  - FUNC

BOOL and BOOL2                    #BOOL3
                                  #Implicitely typecast (using $boolean())
BOOL or BOOL2                     #BOOL3
                                  #Implicitely typecast (using $boolean())
BOOL.$not()->BOOL2                #Implicitely typecast (using $boolean())

                                  ┌────────────┐
                                  │   NUMBER   │
                                  └────────────┘

VAL.$number()->NUM                #Typecast:
                                  #  - BOOL -> 0|1
                                  #  - 'NUM' -> NUM
                                  #  - else error

$formatBase(NUM[, NUM2])->STR     #NUM2 is radix (def 10)

$formatNumber(NUM, 'NUM_FORMAT'
 [, NUM_FORMAT_OBJ])->STR         #
$formatInteger(INT, 'NUM_FORMAT')
 ->STR                            #
$parseInteger
 (STR, 'NUM_FORMAT')->INT         #
NUM_FORMAT                        #XPath format. Not documented yet

NUM < <= > >= NUM2                #BOOL

NUM + - * / % NUM2                #NUM3

NUM.$power(NUM2)->NUM3            #
NUM.$sqrt()->NUM2                 #

NUM.$abs()->NUM2                  #
NUM.$floor|$ceil()->NUM2          #
NUM.$round([NUM2])->NUM3          #NUM2 is number of decimals (can be negative)

$random()->NUM                    #0 to 1, pseudo-random

$min|max(NUM_ARR)->NUM2           #
$sum|average(NUM_ARR)->NUM2       #

                                  ┌────────────┐
                                  │   STRING   │
                                  └────────────┘

VAL.$string([BOOL])->STR          #Typecast using JSON.stringify(VAL)
                                  #If BOOL true (def false): JSON.stringify(VAL, null, 2)
                                  #Exceptions:
                                  #  - Inf|NaN: error
                                  #  - FUNC: empty STR

STR < <= > >= STR2                #BOOL

STR & STR2                        #STR3. Concat
                                  #Implicitely typecast (using $string())

STR.$length()->NUM                #NUM of codepoints

STR.$contains(STR2)->BOOL         #
STR.$substring(NUM[, NUM2])->STR2 #From index NUM (included)
                                  #  - can be negative from end
                                  #For NUM2 chars (def: all)
STR.$substringBefore(STR2)->STR3  #From beginning to first occurence of STR2 (excluded) (if any)
STR.$substringAfter(STR2)->STR3   #From first occurence of STR2 (excluded) (if any) to end

STR.$uppercase|$lowercase()->STR2 #
STR.$trim()->STR2                 #Trim whitespaces (space \t \n \r)
                                  #Also squash multiple whitespaces into single spaces
STR.$pad(NUM[, 'CHAR'])->STR2     #Pad to right, if needed, using CHAR (def: space)
                                  #Pad to left if NUM negative

$join(STR_ARR[, STR2])->STR3      #Def STR2: ''
STR.$split(STR2|REGEXP[, NUM])    #STR2 can be empty, to split char by char
 ->STR3_ARR                       #NUM truncates resulting ARR length

STR.$base64encode|encode()->STR2  #
STR.$encode|decodeUrl[Component]()
 ->STR2                           #

                                  ┌────────────┐
                                  │   OBJECT   │
                                  └────────────┘

OBJ.VAR                           #VAL

OBJ.`VAR`                         #Needed when VAR contains ASCII punctuation (except for - _ ' " ` \), due to ambiguity with operators
OBJ.$lookup('VAR')->VAL           #Or when starts with $, due to ambiguity with $VAR

OBJ.*                             #All values, as ARR
OBJ.**                            #All values, deeply (depth-first search), as ARR

VAL.{...}                         #Like {...} but using VAL as $, i.e. OBJ templating|transform
                                  #E.g. {"a": 2}.{"a": a * 3}

OBJ.$keys()->'VAR'_ARR            #If duplicate (due to iterations), unique only
OBJ.$spread()->OBJ2_ARR           #Each OBJ2 contains single entry, i.e. {VAR: VAL}

OBJ.$each(FUNC(VAL, 'VAR')->VAL2)
 ->VAL2_ARR                       #Maps
OBJ.$sift
 (FUNC(VAL, 'VAR', OBJ)->BOOL)
 ->OBJ                            #Filter VARs

$merge(OBJ_ARR)->OBJ              #Shallow merge
$clone(OBJ|ARR)->OBJ2|ARR2        #Deep clone

                                  ┌───────────┐
                                  │   GROUP   │
                                  └───────────┘

OBJ_ARR{...}                      #Like {...} but mapping every non-literal EXPR over OBJ_ARR
                                  #{...} is evaluated only once, i.e. returns an OBJ, e.g.:
                                  #  - [{"a": 1}, {"a": 2}]{"a": a} -> {"a": [1, 2]}
                                  #  - [{"a": {"b": 1}}, {"a": {"b": 2}}]{"a": a.b} -> {"a": [1, 2]}
                                  #I.e. meant for grouping
                                  #EXPR can be deep, e.g.:
                                  #  - [{"a": 1}, {"a": 2}]{"a": {"b": a}} -> {"a": {"b": [1, 2]}}
                                  #But not inside EXPR with explicit $ binding, e.g.:
                                  #  - [{"a": 1}, {"a": 2}]{"a": $.{"b": a}} -> {"a": [{"b": 1}, {"b": 2}]}
                                  #  - [{"a": 1}, {"a": 2}]{"a": $.[a]} -> {"a": [[1], [2]]}

(OBJ_ARR{...})                    #Must be wrapped in () if not last in query, due to operator precedence

OBJ_ARR{VAR: $.(... OP ...), ...}
OBJ_ARR{VAR: $.($FUNC(...)), ...} #$.(...) must be used in any EXPR using FUNCs|operators

OBJ_ARR{VAR: VAL.$FUNC(...), ...} #Except when using VAL.$FUNC() notation

OBJ_ARR{VAR: $FUNC(VAL), ...}     #Calls $FUNC(ARR), i.e. aggregates

                                  ┌────────────┐
                                  │   MUTATE   │
                                  └────────────┘

| ... | OBJ[, "VAR"[_ARR]] |      #FUNC(OBJ2)->OBJ3
                                  #OBJ2.(...) = $merge([OBJ2.(...), OBJ])
                                  #Also deletes OBJ2.(...).VAR
                                  #OBJ2.(...) must be an OBJ
                                  #OBJ2.(...) is $ in OBJ and "PROP"
                                  #  - i.e. can transform, not just set

OBJ2 ~> | ... | ... |             #Usually called this way
                                  #E.g. {"a": {"b": 2}} ~> | a | {"b": b * 2} | -> {"a": {"b": 4}}

                                  ┌───────────┐
                                  │   ARRAY   │
                                  └───────────┘

ARR[NUM]->VAL                     #0-based
                                  #Can be negative (from end)
                                  #Can be float (rounded down)
ARR[NUM_ARR]->ARR2                #

[NUM..NUM2]->NUM3_ARR             #From NUM (included) to NUM2 (included)
[NUM..NUM2, NUM3, ...]
[NUM..NUM2, NUM3..NUM4, ...]      #Concat

VAL.[...]                         #Like [...] but using VAL as $, i.e. ARR templating|transform
                                  #E.g. {"a": 2}.[a, a * 2]

ARR[BOOL]->ARR2                   #Filters
                                  #Implicitely typecast (using $boolean())

ARR^(NUM|STR,...)->ARR            #Order by NUM|STR
                                  #$ in NUM|STR is each ARR item
                                  #E.g. ARR^($)
ARR^(<NUM|STR,...)
ARR^(>NUM|STR,...)                #Order (def: <, i.e. asc)
$sort
 (ARR[, FUNC(VAL, VAL2)->BOOL])
 ->ARR2                           #Def FUNC: > (i.e. ARR must STR|NUMs)

$count(ARR)->NUM                  #Length

$append(ARR, ARR2)->ARR3          #Concat
$distinct(ARR)->ARR2              #Only keep unique values

$reverse(ARR)->ARR2               #
$shuffle(ARR)->ARR2               #

$map
 (ARR, FUNC(VAL, NUM, ARR)->VAL)
 ->ARR2                           #
$filter
 (ARR, FUNC(VAL, NUM, ARR)->BOOL)
 ->ARR2                           #
$single
 (ARR, FUNC(VAL, NUM, ARR)->BOOL)
 ->VAL                            #Like $filter(...)[0] but throws if less|more than one match
$reduce(ARR,
 FUNC(MEMO, VAL, NUM, ARR)->MEMO
 [, MEMO])->ARR2                  #Def MEMO: first VAL

$zip(ARR,...)->ARR2               #ARR2[m][n] is args[n][m]

                                  ┌────────────┐
                                  │   REGEXP   │
                                  └────────────┘

/REGEXP/[FLAGS]                   #REGEXP. Is actually FUNC described below
                                  #Not a STR, i.e. no quotes
                                  #FLAGS i or m.

REGEXP(STR)[->MATCH_OBJ]
STR ~> REGEXP                     #Returns next MATCH_OBJ, or undefined if none
MATCH_OBJ.match                   #STR
MATCH_OBJ.start|end               #NUM
MATCH_OBJ.groups                  #STR_ARR. (...) groups (except if (?:...))
MATCH_OBJ.next()->MATCH_OBJ2      #

REGEXP-LIKE ==>                   #Can be done by passing a FUNC with same signature as REGEXP

STR.$match(REGEXP[, NUM])         #Same logic, iterating until end
 ->MATCH_OBJ_ARR                  #NUM truncates resulting ARR length
STR.$contains(STR2|REGEXP)->BOOL  #

STR.$replace
 (REGEXP, FUNC(MATCH_OBJ)->STR2)  #Replace all
STR.$replace(REGEXP, STR2)        #Same with STR2 instead of FUNC
                                  #STR2 can use:
                                  #  - $0: whole match
                                  #  - $NUM: parenthesis group
                                  #  - $$: escaped $
STR.$replace(STR2, ...)           #Same with STR2 instead of REGEXP
STR.$replace(..., NUM)            #Only do NUM replacements

                                  ┌──────────┐
                                  │   DATE   │
                                  └──────────┘

"DATE"                            #"YYYY-MM-DDThh:mm:ssZ"
DATE_NUM                          #Epoch in ms

$millis()->DATE_NUM
$now()->"DATE"                    #Current time. Same value inside same QUERY

DATE_NUM.$fromMillis()->"DATE"    #
"DATE".$toMillis()->DATE_NUM      #

$now('DATE_FORMAT')->"DATE"
DATE_NUM.$fromMillis
 ('DATE_FORMAT')->"DATE"
"DATE".$toMillis('DATE_FORMAT')   #Def DATE_FORMAT: ISO 8601 (as above)
 ->DATE_NUM                       #DATE_FORMAT: not documented yet
$now(..., 'TZ')->"DATE"
DATE_NUM.$fromMillis(..., 'TZ')
 ->"DATE"                         #Def 'TZ': UTC