Module JsonAccess

Provides functions to extract data from an unknown data structure as is typically produced by JSON.parse(sometext).

All methods typically return a Maybe<T> which is either the expected result type or a JsonAccessError. To easily combine the methods, the all also accept a Maybe<unknown> and in case it is actually an error, the input value is immediately returned.

NOTE: While the functions are called json..., the input of most is not some string but rather the output of jsonParse of type unknown. Insofar the functions can generally be used to savely pick typed values out of unknown data.

There are four sets of functions:

jsonAsX

These check if a given value is of type X and return the value or a JsonAccessError. See jsonAsString, jsonAsNumber, jsonAsNumberType, jsonAsBoolean, jsonAsObject, jsonAsArray, jsonAsTypedArray, jsonAsType, jsonAsInstance.

jsonGetX

These pick an index from an array or field from an object and call the respective jsonAsX function on the result. See jsonGetString, jsonGetNumber, jsonGetNumberType, jsonGetBoolean, jsonGetObject, jsonGetArray, jsonGetTypedArray, jsonGetType, jsonGetInstance.

jsonXxxConverter

These return one-parameter functions which, given a piece of data, perform a fixed conversion or return a JsonAccessError. There are only three of them, because for example jsonAsNumber (no parentheses) is its own converter. The generated functions are intented to be used, for example as a parameter of jsonAsInstance. See jsonTypedArrayConverter, jsonTypeConverter, jsonInstanceConverter.

jsonXxxGetter

These create functions which, when applied to some data, perform the respective jsonGetX for a fixed field provided to jsonXxxGetter. See jsonStringGetter, jsonNumberGetter, jsonNumberTypeGetter, jsonBooleanGetter, jsonObjectGetter, jsonArrayGetter, jsonTypedArrayGetter, jsonTypeGetter, jsonInstanceGetter.

Example

Consider an API which is expected to deliver an object like { item: string, price: number} and we want to savely access the values.

   const text = '{"id": "socks", "price": 3.14}';
   const data = jsonParse(text);
   type Item = { id: string; price: number };
   const item: Maybe<Item> = jsonAsType(
     data,
     [jsonStringGetter('id'), jsonNumberGetter('price')],
     (id, p) => ({ id: id, price: p })
   );
   if (!isValid(item)) {
     throw item; // a JsonAccessError
   }
   // continue with item properly typed as Item
Copy

Instead of using type Item one could create a respective class, use jsonAsInstance and pass the constructor as the third parameter instead of the elaborate lambda to create the item.