# gizmodel/sql/types/json

JSON as PostgreSQL 16 reads, prints and queries it: JSON text as exact items (json, jsonb), and SQL/JSON paths, the jsonpath type: its parser (jsonpath_scan.l, jsonpath_gram.y), its canonical text (jsonpath_out) and its evaluation (jsonpath_exec.c). Lax mode unwraps arrays and ignores structural errors; strict mode reports them; predicates are true, false or unknown. Numbers stay numeric text, as jsonb keeps them.

```gizlang
import * as Json from "gizmodel/sql/types/json";
```

## Types

### `JV`

```gizlang
type JV = { k: i64; s: string; items: Vec<JV>; keys: Vec<string>; off: i64; base: i64; plain: bool; }
```

A JSON value with exact numbers. `k` is its kind (J*); `s` a boolean's or number's text, or a
string's characters; `items` an array's elements or an object's values, `keys` the object's
keys in jsonb order (shorter first, then by bytes; one of each). `off` and `base` place a
container in PostgreSQL's jsonb binary form, which .keyvalue() reports as the object's id.

- `k`: `i64`
- `s`: `string`
- `items`: `Vec<M161.JV>`
- `keys`: `Vec<string>`
- `off`: `i64`
- `base`: `i64`
- `plain`: `bool`

### `JsonParts`

```gizlang
type JsonParts = { kind: i64; keys: Vec<string>; values: Vec<string>; }
```

A JSON text's top-level parts as written: an array's elements, or an object's keys (decoded)
and values. `kind` is JARR, JOBJ or, for a scalar, its kind; none when the text is not JSON.

- `kind`: `i64`
- `keys`: `Vec<string>`
- `values`: `Vec<string>`

### `JsonPath`

```gizlang
type JsonPath = { lax: bool; root: JP; keyvalue: bool; }
```

A parsed path; `keyvalue` when it calls .keyvalue(), whose ids need the jsonb layout.

- `lax`: `bool`
- `root`: `M161.JP`
- `keyvalue`: `bool`

### `Selection`

```gizlang
type Selection = { items: Vec<JV>; complete: bool; }
```

What a path selects: its items, and whether the walk completed (an error ends it in silent mode).

- `items`: `Vec<M161.JV>`
- `complete`: `bool`

## Functions

### `container`

```gizlang
function container(v: JV): bool
```

Whether V is an array or an object.

### `readJson`

```gizlang
function readJson(text: string): JV throws DbError
```

A JSON text as an item tree; 22P02 when it is not JSON.

Effects: fail, alloc.

### `readPlain`

```gizlang
function readPlain(text: string): JV throws DbError
```

A JSON text as written (SQL/JSON of Oracle): objects keep their key order and duplicate keys, numbers their
digits (the exponent mark in upper case).

Effects: fail, alloc.

### `jvText`

```gizlang
function jvText(v: JV): string
```

An item as jsonb text: ", " and ": " between parts, as PostgreSQL prints jsonb.

Effects: fail, alloc.

### `jvCompact`

```gizlang
function jvCompact(v: JV): string
```

An item as JSON text without the spaces.

Effects: fail, alloc.

### `jvListText`

```gizlang
function jvListText(items: Vec<JV>): string
```

Items as the text of a jsonb array of them.

Effects: fail, alloc.

### `jsonbSetPath`

```gizlang
function jsonbSetPath(doc: string, path: Vec<string>, value: string, mode: string): string throws DbError
```

jsonb_set, jsonb_insert or jsonb_delete_path (`mode` as setPath) of jsonb text `doc`.

Effects: fail, alloc.

### `jsonbAssign`

```gizlang
function jsonbAssign(doc: string, path: Vec<string>, numeric: Vec<bool>, value: string): string throws DbError
```

UPDATE ... SET j[k1][k2]... = value (PostgreSQL's jsonb subscript assignment): a missing key or element is made, an
object for a text subscript and an array for an integer one; an array grows with nulls to the index. `doc` "" is
SQL NULL. `numeric` tells for each subscript whether it is an integer.

Effects: fail, alloc.

### `jsonbDelete`

```gizlang
function jsonbDelete(doc: string, keys: Vec<string>, byIndex: bool, index: i64): string throws DbError
```

jsonb - key, jsonb - keys (an array's string items or an object's keys) and jsonb - index.

Effects: fail, alloc.

### `jsonbConcat`

```gizlang
function jsonbConcat(left: string, right: string): string throws DbError
```

jsonb || jsonb: two objects merge (the right one's keys win); otherwise an array of the left items
then the right items, a scalar or an object counting as one item.

Effects: fail, alloc.

### `jsonbStripNulls`

```gizlang
function jsonbStripNulls(doc: string): string throws DbError
```

jsonb_strip_nulls: object fields whose value is null are left out, at every depth.

Effects: fail, alloc.

### `jsonbPretty`

```gizlang
function jsonbPretty(doc: string): string throws DbError
```

jsonb_pretty: one item a line, four spaces a level.

Effects: fail, alloc.

### `jsonbCompare`

```gizlang
function jsonbCompare(a: JV, b: JV): i64
```

PostgreSQL's jsonb ordering: an object above an array above a boolean above a number above a string above null.
Containers with more items are greater; others compare item by item (an object key, then its value), numbers as
numbers, strings by bytes and false before true.

Effects: fail, alloc.

### `jsonPart`

```gizlang
function jsonPart(text: string, path: Vec<string>, only: i64): Option<string>
```

The part of JSON `text` that `path` reaches, as written (jsonb text gives jsonb text): each
step a key of an object, or an element index of an array (from the end when negative), the
last of equal keys. `only`: JOBJ or JARR when every step must be a key (-> text) or an index
(-> integer), else 0. None when the path reaches nothing.

Effects: fail, alloc.

### `jsonPartText`

```gizlang
function jsonPartText(part: string): Option<string>
```

A JSON part as ->> and #>> give it: a string's characters, null as none, other parts as written.

Effects: fail, alloc.

### `jsonParts`

```gizlang
function jsonParts(text: string): Option<JsonParts>
```

The top-level parts of the JSON TEXT, or none when it is not JSON.

Effects: fail, alloc.

### `parsePath`

```gizlang
function parsePath(source: string): JsonPath throws DbError
```

A jsonpath text parsed: 42601 for its syntax, 22P02 when it is empty.

Effects: fail, alloc.

### `jsonpathInput`

```gizlang
function jsonpathInput(source: string): string throws DbError
```

jsonpath input as PostgreSQL stores and prints it.

Effects: fail, alloc.

### `select`

```gizlang
function select(path: JsonPath, target: JV, vars: JV, hasVars: bool, silent: bool, first: bool, tz: bool): Selection throws DbError
```

The items `path` selects in `target`, with `vars` when given (an object; without them each
variable is null). An error ends the walk with the error unless `silent` hides it (a missing
variable it does not). `first`: stop at the first item, as only whether one exists matters.

Effects: fail, alloc.

### `pathQuery`

```gizlang
function pathQuery(target: string, source: string, varsText: string, hasVars: bool, silent: bool, first: bool, tz: bool): Selection throws DbError
```

jsonb_path_query and its kin over texts: the target and vars jsonb, the path.

Effects: fail, alloc.

## Constants

### `JNULL`

```gizlang
const JNULL: i64 = 0
```

JSON kind: null.

### `JBOOL`

```gizlang
const JBOOL: i64 = 1
```

JSON kind: a boolean.

### `JNUM`

```gizlang
const JNUM: i64 = 2
```

JSON kind: a number.

### `JSTR`

```gizlang
const JSTR: i64 = 3
```

JSON kind: a string.

### `JARR`

```gizlang
const JARR: i64 = 4
```

JSON kind: an array.

### `JOBJ`

```gizlang
const JOBJ: i64 = 5
```

JSON kind: an object.

