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.
import * as Json from "gizmodel/sql/types/json";Types
JV
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:i64s:stringitems:Vec<M161.JV>keys:Vec<string>off:i64base:i64plain:bool
JsonParts
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:i64keys:Vec<string>values:Vec<string>
JsonPath
type JsonPath = { lax: bool; root: JP; keyvalue: bool; }A parsed path; keyvalue when it calls .keyvalue(), whose ids need the jsonb layout.
lax:boolroot:M161.JPkeyvalue:bool
Selection
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
function container(v: JV): boolWhether V is an array or an object.
readJson
function readJson(text: string): JV throws DbErrorA JSON text as an item tree; 22P02 when it is not JSON.
Effects: fail, alloc.
readPlain
function readPlain(text: string): JV throws DbErrorA 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
function jvText(v: JV): stringAn item as jsonb text: ", " and ": " between parts, as PostgreSQL prints jsonb.
Effects: fail, alloc.
jvCompact
function jvCompact(v: JV): stringAn item as JSON text without the spaces.
Effects: fail, alloc.
jvListText
function jvListText(items: Vec<JV>): stringItems as the text of a jsonb array of them.
Effects: fail, alloc.
jsonbSetPath
function jsonbSetPath(doc: string, path: Vec<string>, value: string, mode: string): string throws DbErrorjsonb_set, jsonb_insert or jsonb_delete_path (mode as setPath) of jsonb text doc.
Effects: fail, alloc.
jsonbAssign
function jsonbAssign(doc: string, path: Vec<string>, numeric: Vec<bool>, value: string): string throws DbErrorUPDATE ... 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
function jsonbDelete(doc: string, keys: Vec<string>, byIndex: bool, index: i64): string throws DbErrorjsonb - key, jsonb - keys (an array's string items or an object's keys) and jsonb - index.
Effects: fail, alloc.
jsonbConcat
function jsonbConcat(left: string, right: string): string throws DbErrorjsonb || 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
function jsonbStripNulls(doc: string): string throws DbErrorjsonb_strip_nulls: object fields whose value is null are left out, at every depth.
Effects: fail, alloc.
jsonbPretty
function jsonbPretty(doc: string): string throws DbErrorjsonb_pretty: one item a line, four spaces a level.
Effects: fail, alloc.
jsonbCompare
function jsonbCompare(a: JV, b: JV): i64PostgreSQL'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
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
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
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
function parsePath(source: string): JsonPath throws DbErrorA jsonpath text parsed: 42601 for its syntax, 22P02 when it is empty.
Effects: fail, alloc.
jsonpathInput
function jsonpathInput(source: string): string throws DbErrorjsonpath input as PostgreSQL stores and prints it.
Effects: fail, alloc.
select
function select(path: JsonPath, target: JV, vars: JV, hasVars: bool, silent: bool, first: bool, tz: bool): Selection throws DbErrorThe 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
function pathQuery(target: string, source: string, varsText: string, hasVars: bool, silent: bool, first: bool, tz: bool): Selection throws DbErrorjsonb_path_query and its kin over texts: the target and vars jsonb, the path.
Effects: fail, alloc.
Constants
JNULL
const JNULL: i64 = 0JSON kind: null.
JBOOL
const JBOOL: i64 = 1JSON kind: a boolean.
JNUM
const JNUM: i64 = 2JSON kind: a number.
JSTR
const JSTR: i64 = 3JSON kind: a string.
JARR
const JARR: i64 = 4JSON kind: an array.
JOBJ
const JOBJ: i64 = 5JSON kind: an object.